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Preface 



This publication is intended for the 
general CMS user. It contains infornation 
describing the interactive facilities of 
CHS, and includes examples showing you how 
to use CMS. 

"Part 1. Understanding CMS" contains 
sections that describe, in general tens, 
the CMS facilities and the CMS and CP 
coMands that you can use to control your 
virtual nachine. If you are an experienced 
programner who has used interactive 
terminal systems before, you lay be able to 
refer directly to the YM/ 370; CMS Command 
and Macro Reference publication to find 
specific details about CHS commands that 
are summarized in this part. Otherwise, 
you may need to refer to later sections of 
this publication to gain a broader 
background in using CHS. The topics 
discussed in Part 1 are: 

• What It Means To Have a CMS Virtual 
Machine 

• TM/370-CMS Environments and Mode 
Switching 

• What You Can Do with VH/370-CHS Commands 

• The CMS File System 

• The CMS Editor 

• Introduction to the EXEC Processor 

• Using Real Printers, Punches, Readers, 
and Tapes 



"Part 2. Program Development Using CMS" 
is primarily for applications programmers 
who want to use CMS to develop and test OS 
and DOS programs under CMS- The topics 
discussed in Part 2 are: 

• Developing OS Programs Under CMS 

• Developing DOS Programs Under CMS 

• Using Access Method Services and VSAM 
Under CMS and CMS/DOS 

• How VH/370 Can Help You Debug Your 
Programs 

• Using the CMS Batch Facility 

• Programming for the CMS Environment 

"Part 3- Learning To Use EXEC" gives 
detailed information on creating EXEC 



procedures to use with 
discussed in Part 3 are: 



CMS. The topics 



• Building EXEC Procedures 

• Using EXECs with CHS Commands 

• Refining Your EXEC Procedures 

• Writing Edit Hacros 

I "Part 4. Learning To Use the HELP 
i Facility" contains descriptions and 
i examples of the use of HELP facility format 
I words in creating HELP description files. 

"Appendix A: Summary of CHS Commands" 
lists the commands available in the CHS 
command environment. 

"Appendix B: Summary of CP Commands" 
lists the CP command privilege classes and 
summarizes the commands available in the CP 
command environment. 

"Appendix C: Considerations for 3270 
Display Terminal Users" discusses aspects 
of VM/37 and CHS that are different or 
unigue when you use a 3270 display 
terminal. 

"Appendix D: Sample Terminal Sessions" 
shows sample terminal sessions for: 

• Using the CHS editor and CHS file system 
commands 

• Using line-number editing with the CHS 
editor 

• Creating, assembling, and executing an 
OS program in CHS 

• Creating, assembling, and executing a 
DOS program in CHS/DOS 

• Using access method services in CHS 



TEBHIHOLOGY 



Some of the following terms are used, for 
convenience, throughout this publication: 

• The term "CHS/DOS" refers to the 
functions of CHS that become available 
when you issue the command 

set dos on 

CHS/DOS is a part of the normal CHS 
system, and is not a separate system. 
Users who do not use CHS/DOS are 
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soaetimes referred to as OS users, since 
they use the OS simulation functions of 
CMS. 

The term "CHS files" refers exclusively 
to files that are in the fixed block 
format used by CMS file system commands. 
VSAM and OS data sets and DOS files are 
not compatible with the CMS file format, 
and cannot be manipulated using CMS file 
system commands. 

The terms "disk" and "virtual disk" are 
used interchangeably to indicate disks 
that are in your CMS virtual machine 
configuration. Where necessary, a 
distinction is made between 
CMS- formatted disks and disks in OS or 
DOS format. 

"3270" refers to a series of display 
devices, namely, the IBM 3275, 3276 
Controller Display Station, and 3277 and 
3278 Display Stations- A specific 
device type is used only when a 
distinction is required between device 
types. 

Information about display terminal 
usage also applies to the IBM 3138, 
3148, and 3158 Display Consoles when 
used in display mode, unless otherwise 
noted. 

Any information pertaining to the IBM 
3284 or 3286 Printer also pertains to 
the IBM 3287, 3288, and 3289 printers, 
unless otherwise noted. 

"3330" refers to the IBM 3330 Disk 
Storage Models 1, 2, and 11, the IBM 
3333 Disk Storage and Control Models 1 
and 11, and the IBM 3350 Direct Access 
Storage in 3330 compatibility mode. 

"2305" refers to the IBM 2305 Fixed Head 
Storage, Models 1 and 2. 

"3340" refers to the IBM 3340 Direct 
Access Storage Facility and the IBM 3344 
Direct Access Storage. 

"3350" refers to the IBM 3350 Direct 
Access Storage device when used in 
native mode. 

Any information pertaining to the IBM 
2741 terminal also applies to the IBM 
3767 terminal, unless otherwise noted. 

370x refers to the 3704/3705 
Communications Controllers. 



• "FB-512" refers to the IBM 3370 and 3310 
Direct Access Storage Devices. 

For a glossary of VM/370 terms, see the 
IMI li^iijal H^Sitil® Facility/370; Gl ossary 
and Master Index, GC20-1813. 



PREEEQDISITE PUBLICATIONS 



If this is the first time you have used a 
computer terminal, you should consult the 
IM/370 Terminal Dser^s Guide, GC20-1810, 
for information on using your terminal. 



If your terminal is a 3767 

Communications Terminal, then I BM 3767 

Operator *s Guide, GA18~2000, is a 
prerequisite. 



The IBM Virtual Machine Facility/370; 
Introduction, GC20-1800, contains an 
overview of the VM/370 system and its 
components, and lists the programs and 
products that are supported in CMS. 



COREQDISITE PUBLICATIONS 



The IBM Virtual Machine Faci li ti/37 ; CMS 
Command and Macro Reference, GC20-1818, is 
a companion to this user's guide. It 
contains complete format descriptions of 
the CMS commands; EDIT subcommands; EXEC 
control statements, built-in functions, and 
special variables; DEBUG subcommands; and 
CMS assembler language macros that are 
discussed or used in examples in this book. 



"3370" refers to the 
Access Storage Device- 



IBM 3370 Direct 



I • "3310" refers to the IBM 3310 Direct 
I Access Storage Device- 



IBM Virtual Mach ine FacilitY/370 ; System 
Messages, GC20-1808, contains the 
responses, error messages, and return codes 
issued by the CBS commands, and EDIT and 
DEBUG subcommands referenced in this 
publication, as well as a complete list of 
the error messages issued by the EXEC 
processor . 



To use CMS, you should be familiar with 
the control program (CP) component of 
VM/370. The CP commands available to 
general users are described in IBM Virtual 
Machine Facility/370; CP Commaiid Referencg 
for~General Users, GC20-1820. If you" are 
using CMS to develop programs to run under 
other operating systems, see IBM Virtual 
Machine FacilitY/370; fige rating Sxsteis in 
a Virtual Machine, GC20-1821. 
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RELATED VM/370 PUBLICATIONS 

Additional descriptions of various CHS 
functions and comaands that are normally 
used by system support personnel are 
described in 

ISH lillual Machine Fac ili t j[^370 : 

System Programmer's Guide, GC20-1807 

gjEeratgrJ^s Guide, GC 20- 1806 

Planning and System Generation Guide, 
GC2 0-1801 



IPCS CHS commands are described in the 
IBH VM/320: Interactive Problem Control 
System (IPCS) Oser^i GuIde7~GC2^-1823,"and 
not in this publication. 

Information describing the CHS command 
CPEBEP, a command used to generate output 
reports from VH/370«s error recording 
records, is contained in the: 

JBH Virtual Machine FacilitY/370; 

OLTSEP and Error Recording Guide, 
GC20-1809 



Details on the use of OS/VS EREP 
operands, reguired to make use of CPEHEP, 
are contained in: 

OS/VS, DOS/VSE, IMZ320 Environmental 
l5S2£j5in5, Editing, and Printing 
il5aiaj# GC 28- 077 2. 

There are three publications available 
as ready reference material when you use 
VH/370 and CHS. They are: 

im li^tual Machine Fac ili ty/37 : 



fisicJS Guide for Users, GX2 0-1926 

Commands (General User) , GX 2 0-1961. 

Commands (Other than General User) , 
GX20-T995. 



If you use the Remote Spooling 
Communications Subsystem, see the IjBH 
2i:£tual M ac hine racility/370; gemote 
SEOoling Communications Subsystem (ggCS) 
5sirJ^s"'Guide, GC20-1816. 



Assembler language programmers may find 
information about the VH/370 assembler in 
OS/VS, EOS/VS, and VH/370 Assembler 
Language, GC33-U010, and CS/VS and VH/370 
Assembler Programmer's Guide, GC33-4021. 



BELATED PUBLICATIONS FOB 
HETHOD SERVICES USERS 



VSAB AND ACCESS 



CHS support of access method services is 
based on EOS/VS access method services. The 
control statements that you can use are 
described in DOS/VS Access Hethod Servi ces 
Usgr's Guide, GC33-5382. ~ Error"" messages 
produced by the access method services 
program, and return codes and reason codes, 
are listed in DOS/VS Hessages, GC33-5379. 

For a detailed description of DOS/VS 
VSAH macros and macro parameters, refer to 
the DOJ/VS Supervisor and I/O Hacros, 
GC33-5373. For information on OS/VS VSAH 
macros, refer to OS/VS Virtual Storage 
Access Hethod (VSAH) Programmer's Guide, 
GC26-3818. 



RELATED PUBLICATIONS FOR CHS/DOS USERS 



The CHS ISERV command invokes the DOS/VS 
ESERV program, and uses, as input, the 
control statements that you would use in 
DOS/VS. These control statements are 
described in Guide to the DCS/VS Assembler, 
GC33-4024. 

Linkage editor control statements, used 
when invoking the DOS/VS linkage editor 
under CHS/DOS, are described in DOS/VS 
system Control Statements, GC3 3-5376. 
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HBLATED VM/370 PUBLICATIONS 

Additional descriptions of various CHS 
functions and coiiands that are normally 
used by system support personnel are 
described in 

IBM Virtual Machine Fac ili t2^320 : 

Sfystem Programmer's Guide, GC 20- 1807 

operator's Guide, GC20-1806 

Planning and System Generation Guide, 
GC2 0-1801 



IPCS CMS commands are described in the 
IBM VMZilO! Interactive Problem Control 
System (IPCS) Dserlg "Guide, GC 2 0-1 82 3, ""and 
not in this publication. 

Information describing the CHS command 
CPEBEP, a command used to generate output 
reports from VH/370«s error recording 
records, is contained in the: 

3IM ZiEtual Hachine Facility/370; 

OLTSEP and Error Recording Guide # 
GC20-T809 



Details on the use of 0S/7S EREP 
operands, required to make use of CPEREP, 
are contained in: 

OS/ys, DOS^VSE, IH/320 Environmental 
Recording. Editing, and Printing 
Program, GC28-0772T'" 

For information on 0S/7S tape label 
processing, discussed with "Label 
Processing in OS Simulation" in this 
publication, refer to: 

OS/ YS 1 Data Man agement Services Guide, 
GC26-387a 

0S/YS2 Data Management Services Guide, 
GC26-3875 

OS/YS Ta£e Labels, GC26-3795 

There are three publications available 
as ready reference material when you use 
YM/370 and CMS. They are: 

IBM Virtual Machine Facility/370: 



Quick Guide for Users, GX20-1926 

Commands (General User), GX20-1961. 

Commands (O ther than General User) , 
GX20-1995. 



If you use the Remote Spooling 
Communications Subsystem, see the IBM 
liliSil Hachine Facility /37O; Remote 
liiiiiliS Communications Subsjstem (RSCS) 
0§§£ls Guide, GC20-1816. 



Assembler language programmers may find 
information about the VM/370 assembler in 
OS/VS, D OS/YS, and VM/370 Assembler 
Language, GC33-«*010, and OS/VS and VM/370 
Assembler Program m er's Guide, GC33-U021. 



RELATED PUBLICATIONS FOR 
HETHOD SERVICES USERS 



VSAM AND ACCESS 



CMS support of access method services is 
I based on DOS/VSE and VSE/VSAM. The control 
statements that you can use are described 
in Using VSE/VSAM Command and Macros, 
SC2'»-514U. Error messages produced by the 
access method services program, and return 
codes and reason codes, are listed in 
2QS/VSE Messages, GC33-5379. 

For a detailed description of VSE/VSAM 
macros and macro parameters, refer to the 
DOS/VSE Macro User^s Guide, GC24-5139. For 
information on OS/YS VSAM macros, refer to 
QS/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide, GC 26- 3818. 



RELATED PUBLICATIONS FOR CMS/DOS USERS 

I The CHS ESERV command invokes the DOS/VSE 
ESERY program, and uses, as input, the 

I control statements that you would use in 
DOS/VSE. These control statements are 

I described in Guide to the DOS/VSE 
Assembler, GC33-a024. 

Linkage editor control statements, used 
I when invoking the DOS/VSE linkage editor 
I under CMS/DOS, are described in DOS/VSE 
i System Control Statements, GC33-5376- 

I For information on DOS/VSE and CMS/DOS 
I tape label processing, refer to the 
I following publications: 

I 5QS/VSE Tape Labels , GC33-5374 

I DOS/VSE Hacro User's Guide, GC24-5139 

I POS/VSE LIOCS, Volume 2, SY33-8560 



Preface 



March 30, 1979 



vi IBM VM/370: CMS User's Guide 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8 

Contents 



The entries in this Table of Contents are accumulative and reflect the 
VM/370 Basic System Extensions Program Product, Program Number 57U8-XX8. 



addition of the 



Summary of Amendments xiii 

PART r. UNDERSTANDING CMS . . .1 

SECTION 1. WHAT IT MEANS TO HAVE A CMS 
VIRTUAL MACHINE ,. . 3 

How You Communicate With VM/370 3 

Getting Commands Into the System ... .5 
Loading CMS in the Virtual Machine: The 
IPL Command 6 

Logical Line Editing Symbols 6 

How VM/370 Responds to Your Commands . .8 

Getting Acguainted With CMS 10 

Virtual Disks and How They Are Defined . 11 

Permanent Virtual Disks. .. 11 

Defining Temporary Virtual Disks ... 12 
Formatting Virtual Disks , - 12 

Sharing Virtual Disks: Linking 13 

Identifying Your Disk To CMS: Accessing. 14 

Releasing Virtual Disks 14 

Releasing Virtual Disks (5748-XX8) . 14. 1 

SECTION 2. VM/370 ENVIRONMENTS AND MODE 

SWITCHING 17 

The CP Environment 17 

The CMS Environment 18 

EDIT, INPUT, and CMS Subset 19 

DEBUG. , 20 

CMS/DOS 21 

Interrupting Program Execution 21 

Virtual Machine Interruptions 22 

Control Program Interruptions 23 

Address Stops and Breakpoints. .... 23 

SECTION 3- WHAT YOU CAN DO WITH 

VM/37 0-CMS COMMANDS 25 

Command Defaults 25 

Commands to Control Terminal 

Communications 25 

Establishing and Terminating 

Communications with VM/370, ,. , . , . 25 
Controlling Terminal Output. ..... 26 

Commands to Control How VM/370 

Processes Input Lines ..28 

Commands to Control How VM/370 

Processes Input Lines (5218-XX8) . . 28.1 
Controlling Keyboard-dependent 

Communications 30 

Commands to Create, Modify, and Move 

Data Files and Programs 31 

Commands that Create Files 31 

Commands that Modify Disk Files. ... 33 

Commands to Move Files 33 

Commands to Print and Punch Files. . - 34 
Commands to Develop and Test OS and CMS 

Programs. , .......35 

Commands to Develop and Test DOS 
Programs. .. .......36 



Commands Used in Debugging Programs. . • 37 
Commands to Reguest Information. .... 38 
Commands to Request Information About 

Terminal Characteristics. ...... 38 

Commands to Request Information About 

Data Files. ......39 

commands to Request Information About 

Your Virtual Disks ....40 

Commands to Request Information About 

Your Virtual Machine. 40 

SECTION 4. THE CMS FILE SYSTEM ..... 43 

CMS File Formats 43 

How CMS Files Get Their Names. ..... 43 

How CMS Files Get Their Names 

(5748-XX8) .... 44 

Duplicating Filenames and Filetypes. . 44 

What Are Reserved Filetypes? ...... 45 

Filetypes for CMS Commands ...... 46 

Output Files: TEXT and LISTING .... 48 

Filetypes for Temporary Files. .... 50 

Filetypes for Documentation- . .... 50 

Filemode Letters and Numbers ...... 51 

When to Specify Filemode Letters: 

Reading Files 52 

When to Specify Filemode Letters: 

Writing Files 54 

How Filemode Numbers are Used 54 

Managing Your CHS Disks. ........ 56 

CMS File Directories .......... 56 

CMS Command Search Order 57 

SECTION 5. THE CMS EDITOR .61 

The EDIT Command ......61 

Writing a File Onto Disk ....... 62 

EDIT Subcommands ...63 

The Current Line Pointer ........65 

Verification and Search Columns. .... 68 

Changing, Deleting, and Adding Lines . . 69 

Describing Data File Characteristics . . 73 

Record Length. ............73 

Record Format 75 

Using Special Characters . . . ... . 76 

Setting Truncation Limits 78 

Entering a Continuation Character in 

Column 72 ... .79 

Serializing Records. .. . . .. . .. 80 

Line- Number Editing. ..81 

Renumbering Lines 82 

Controlling the Editor . . . . ... .. 84 

Communicating with CMS and CP. . . . . 84 

Changing File Identifiers 85 

Controlling the Editor's Displays. . . 86 
Preserving and Restoring Editor 

Settings ......86 

Preserving and Restoring Editor 

Settings (5748-XX8) 86.1 

X, Y, =, ? subcommands ........87 



Contents vii 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp, SC23-902U-1 for 5748-XX8 



What q?o Do When You Run Out of Space , 88 
SuHiBiary of EDIT Subcommands. ...... 91 

SECTION 6- INTRODUCTION TO THE EXEC 
PROCESSOR 95 

Creating EXEC Files 95 

Invoking EXEC Files. 96 

PROFILE EXECS. . . 97 

Executing Your PROFILE EXEC 98 

CMS EXECS and How To Use Them 98 

Modifying CMS EXECs. .100 

SuBiniary of the EXEC Language Facilities. 100 

Arguments and Variables. ...... .101 

Assignment Statements 102 

Built-in Functions and Special 
Variables .103 

Flow Control in an EXEC. . . . . . . .103 

Comparing Variable Symbols and 
Constants . .105 

Doing I/O With an EXEC . .106 

Monitoring EXEC Procedures 107 

Summary of EXEC Control Statements and 
Special Variables ..... .109 

SECTION 7. USING REAL PRINTERS, 

PUNCHES, READERS, AND TAPES 113 

CMS Unit Record Device Support . . . . .113 

Using the CP Spooling System . . . . .113 

Altering Spool Files ....... ..115 

Using Your Card Punch and Card Reader 

in CMS. .116 

Handling Tape Files in CMS . . . ... .118 

Using the CMS TAPE Command . .. . . .119 

Tape Labels in CMS . . . , . . . . . . .121 

Tape Labels in CMS (574 8- XX 8) . . . . . .121 

User Responsibilities (5748-XX8) . . . .122 

Label Processing in OS Simulation 

(5248-XX8) • . . . . . . .122 

Label Processing in CHS/DOS 

(574.8- XX8) , . . . . . .122.7 

CHS TAESL Macro (5748-XX8) ... - - 122.10 
Tape Label Processing by CMS 

Commands (52M-M8) • 122.10 

LABELDEF Command (5748-XM) • - - - - 122.12 
End-of-Volume and End-of-Tape 

Processing (5746-XX8) • - • - - - • 122.13 
Error Processing (5748- XX8) . . . . . 122.14 

The MOVEFILE Command 122 

The MOVEFILE Command (5748-XX8) . . 122.14 
Tapes Created by OS Utility 

Programs. ...... .122 

Tapes Created by OS Utility 

Programs (5748-XX8) . 122.15 

Specifying Special Tape Handling 
options ,.,....,..,.. . .123 
Using the Remote Spooling 
Communications Subsystem (RSCS) . . . .123 

PART 2. PROGRAM DEVELOPMENT USING CMS. .125 

SECTION 8. DEVELOPING OS PROGRAMS UNDER 
CMS . . - . . . ... . . 127 

Using OS Data Sets in CMS. . . .... .129 

Access Methods Supported by CMS. . . ,130 

Using the FILEDEF Command . .131 

Specifying the ddname 131 

Specifying the Device Type 132 

Entering File Identifications 132 



Specifying CMS Tape Label Processing 
(5748-XX8) 133 

Specifying Options ....133 

Creating CMS Files From CS Data Sets . .134 
Creating CMS Files From OS Data Sets 

(574 8-XX8) • 134.1 

Using CHS Libraries .136 

The MACLIB Command . . . . . . ,. ,. . .137 

Using OS Macro Libraries ...... .140 

Using OS Macros Under CMS 141 

Assembling Programs in CBS ...... .143 

Executing Programs 144 

Executing TEXT Files .144 

TEXT LIBRARIES (TXTLIBS) 145 

Resolving External References. ... .146 

Controlling the CMS Loader ..... .147 

Creating Program Modules . . . . . . .149 

Using EXEC Procedures. 149 

SECTION 9. DEVELOPING DOS PBOGRAHS 

UNDER CHS .151 

The CMS/DOS Environment .151 

DL/I in the CMS/DOS Environment 152 

Using DOS Files on DOS Disks ..... .154 

Reading DOS Files. .......... .154 

Creating CHS Files from DOS Libraries. 155 
Using the ASSGN Command,. ....... .156 

Using the ASSGN Command (SJMzMI) • -156.1 
Manipulating Device Assignments- . . .157 

Virtual Machine Assignments .158 

Using the DLBL Command . . . 159 

Entering File Identifications 159 

Using DOS Libraries in CHS/DOS .... .160 

The SSERV Command. . .161 

The RSERV Command 162 

The PSERV Command ... . .162 

The ESERV Command .163 

The DSERV Command .163 

Using DOS Core Image Libraries . . . .164 

Using Macro Libraries .164 

CMS MACLIBs. . .165 

Creating a CMS MACLIB . . .165 

The MACLIB Command .......... .166 

DOS Assembler Language Macros Supported. 169 
Assembling Source Programs ...... .171 

Link-editing Programs in CMS/DOS .... 172 

Linkage Editor Input . . . .... . . .173 

Linkage Editor Output: CMS DOSLIEs . .174 
Executing Programs in CMS/DOS. - ,. . . .175 

Executing DOS Phases ........ .175 

Search Order for Executable Phases . . 176 

Making I/O Device Assignments 177 

Specifying a Virtual Partition Size. .177 
Setting the UPSI Byte. ....... .178 

Debugging Programs in CMS/DOS. .... 178 

Using EXEC Procedures in CMS/DOS . . .179 

SECTION 10. USING ACCESS METHOD 
SERVICES AND VSAM UNDER CMS AND 

CMS/DOS ............... .181 

Executing VSAM Programs Under CMS. . .181 
Using the AMSERV Command ........ 182 

AMSERV Output Listings . .183 

Controlling AMSERV Command Listings. . 184 
Manipulating OS and DOS Disks for Use 

with AMSERV .185 

Data and Mastercatalog Sharing ... .185 

Disk Compatibility .186 



viii IBH VM/370: CHS User's Guide 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8 



Using VM/370 Minidisks 187 

Using The LISTDS Command 187 

Using Temporary Disks 188 

Defining DOS Input and Output Files. . .190 

Using VSAM Catalogs. . 190 

Defining and Allocating Space for 

VSAM files. 194 

Using Tape Input and Output. .... .196 

Defining OS Input and Output Files . - ,197 
Allocating Extents on OS Disks and 

Minidisks 198 

Using VSAM Catalogs. . .199 

Defining and Allocating Space for 

VSAM files - ,202 

Using Tape Input and Output 20U 

Using AMSERV Under CMS 205 

Using the DEFINE and DELETE Functions. 205 
Using the REPRO, IMPORT, and EXPORT 

(or EXPORTRA/IMPORTRA) functions. . .207 
Writing EXECs for AMSERV and VSAM. - .209 

SECTION 11. HOW VM/370 CAN HELP YOU 

DEBUG YOUR PROGRAMS .211 

Preparing to Debug 211 

When a Program Abends - .211 

Resuming Execution After a Program 

Check 212 

Using DEBUG Subcommands to Monitor 

Program Execution 213 

Using Symbols with DEBUG 214 

What To Do When Your Program Loops . , .216 

Tracing Program Activity - .216 

Using the CP TRACE Command .... . .217 

Using the SVCTRACE command ..... .219 

Using CP Debugging Commands - .219 

Debugging with CP After a Program 

Check 220 

Program Dumps 221 

Debugging Modules - .221 

Comparison Of CP And CMS Facilities For 

Debugging ,222 

What Your Virtual Machine Storage Looks 

Like. . .223 

Shared and Nonshared Systems 223 

SECTION 12- USING THE CMS BATCH 

FACILITY 227 

Submitting Jobs to the CMS Batch 

Facility 227 

Input to the Batch Machine 227 

How the Batch Facility Works 230 

Preparing Jobs for Batch Execution - . .231 
Restrictions on CP and CMS Commands 

in Batch Jobs 232 

Batch Facility Output- ..,..-.. .232 
Purging, Reordering, and Restarting 

Batch Jobs 233 

Using EXEC Files for Input to the Batch 

Facility 234 

Sample System Procedures for Batch 

Execution -. 235 

A Batch EXEC for a Non-CMS User. . . .236 

SECTION 13. PROGRAMMING FOR THE CMS 
ENVIRONMENT 239 

Program Linkage 239 

Return Code Handling 240 

Parameter Lists .240 



Calling a CMS Command from a Program . .241 

Executing Program Modules 242 

The Transient Program Area , . . . - .243 

CMS Macro Instructions .243 

Macros for Disk File Manipulation. . .244 
CMS Macros for Terminal 

Communications 250 

CMS Macros for Unit Record and Tape 

I/O .250 

Interruption Handling Macros .... .251 

Updating Source Programs Using CMS . . .251 

The UPDATE Philosophy .252 

Update Files 252 

Sequencing Output Records 254 

Multiple Updates ,257 

The VMFASM EXEC Procedure. ..... .262 

PART 3. LEARNING TO USE EXEC . . . , . .265 

SECTION 14. BUILDING EXEC PROCEDURES - .267 

What is a Token? .267 

Variables 268 

Arguments. .272 

Using the SINDEX Special Variable. . .273 

Checking Arguments .... ,274 

Execution Paths in an EXEC - .275 

Labels in an EXEC Procedure 275 

Conditional Execution with the &IF 

Statement ... .276 

Branching with the SGOTO Statement - .277 
Branching with the SSKIP Statement - .279 
Using Counters for Loop Control. . - .280 
Loop Control with the 6LC0P Statement. 280 

Nesting EXEC Procedures 282 

Exiting From EXEC Procedures .... .283 

Terminal Communications - .284 

Reading CMS Commands and EXEC Control 

Statements from the Terminal. ... .285 

Displaying Data at a Terminal. ... .286 

Reading from the Console Stack ... - .289 

Stacking CMS Commands- - .291 

Stacking Lines for EXEC to Read, . - .292 
Clearing the Console Stack ..... .293 

File Manipulation with EXECs .294 

Stacking EXEC Files - - - -294 

SECTION 15. USING EXECS WITH CMS 
COMMANDS 299 

Monitoring CMS Command Execution ... .299 

Handling Error Returns From CMS 

Commands ,. .300 

Using the 8ERR0R Control Statement . .300 
Using the &RETC0DE Special Variable. .301 

Tailoring CMS Commands for Your Own Use. 302 
Creating Your Own Default Filetypes. .303 

SECTION 16. REFINING YOUR EXEC 
PROCEDURES ,. . . .305 

Annotating EXEC Procedures ...,„. .305 

Error Situations .-. . .306 

Writing Error Messages 306 

Debugging EXEC Procedures 308 

Using CMS Subset 308 

Summary of EXEC Interpreter Logic. . .309 

SECTION 17. WRITING EDIT MACROS. . . . .311 

Creating Edit Macro Files. ...... ,311 

How Edit Macros Work 311 



Contents ix 



Pg. of GC20- 1819-2 Rev March 30, 1979 by Supp. SE23-9024-1 for 57U8-XX8 



The console Stack ....313 

Notes on Using EDIT Subcommands 31^ 

The STACK Subcommand . 317 

An Annotated Edit Macro 318 

Oser-Written Edit Macros 320 

$MACROS 320 

SHARK 321 

SPOINT 323 

$COL 32^ 



PART 4. LEARNING TO USE THE HELP 
FACILITY (5748zXM) 



324.1 



SECTION 18. HELP FILE NAMING CONVENTIONS 

AND CREATION (5748-XX8) • • 324.3 

Naming Conventions (Ilua^XXQ) 324.3 

HELP File Creation (5748::XX8) 324.4 

Enclosing Text (.BX Format Word) 

(5748-XX8) , .324.6 

Placing Comments in HELP Files (.CM 

Format Word) (5748;XX8) 324.7 

Conditional Display of Text (.CS 

Format Word) (5748-XX8) 324.8 

Use of Format Mode~(.FO Format 

Word) (57iL8zXX8) • 324.8 

Indenting Text (.IN and .IL Format 

Words) (5748-XX8) 324.8 

Use of offsets (.OF Format Word) 

(5748-XX8) . . 324.10 

Spacing between Lines of Text (.SP 

Format Word) (5748-XX8) 324.11 

Translating Output Characters (.TR 
Format Word) (5748-XX8) 324.13 

APPENDIXES . 325 

APPENDIX A: SUMMARY OF CMS COMMANDS. . .327 



APPENDIX B: SUMMARY OF CP COMMANDS . . .333 

APPENDIX C: CONSIDERATIONS FOR 3270 
DISPLAY TERMINAL USERS. ....... . .339 

Entering Commands .339 

Setting Program Function Keys. .... .339 

Controlling the Display Screen . . . . .340 
Console Output .342 

Signaling Interruptions 343 

Halting Screen Displays. ...... .344 

Using the CMS Editor with a 3270 . , . .344 
Entering EDIT Subcommands. ..... .344 

Controlling the Display Screen ... .346 

The Current Line Pointer ...... .347 

Using Program Function Keys. .... .348 

Using the Editor in Line Mode. ... .348 

Using Special Characters on a 3270 . .349 

Using APL with a 3270 ,350 

Error Situations .351 

Leaving the APL Environment. 351 

Using the 3277 Text Feature .352 

Error Situations 352 

Leaving the Text Environment 352 

APPENDIX D: SAMPLE TERMINAL SESSIONS . .353 
Sample Terminal Session Using the 

Editor and CMS File System Commands . .354 
Sample Terminal Session Using 

Line-Number Editing 362 

Sample Terminal Session For OS 

Programmers 365 

Sample Terminal Session for DOS 

Programmmers. 369 

Sample Terminal Session Using Access 

Method Services .375 

INEEX. .383 



X IBM VM/370: CMS User's Guide 



FIGORES 



Figure 1. VM/370 Environments and Mode Figure 15. 

Switching. . . . ...2U 

Figure 2. Filetypes ased by CMS 

Conmands 47 Figure 16. 

Figure 3. Filetypes Used in CMS/DOS 50 

Figure 4. How CMS Searches for the Figure 17. 

Command to Execute. ............ 59 Figure 18. 

Figure 5- Positioning the Current Line 

Pointer.......... ......68 Figure 19, 

Figure 6. Number of Records Handled by Figure 20, 

the Editor .75 

Figure 7. Summary of EDIT Subcommands Figure 21. 

Macros .......91 

Figure 8, Summary of EXEC Built"-In Figure 22. 

Functions. 103 

Figure 9. Summary of EXEC Control Figure 23. 

Statements. ..................109 

Figure 10- EXEC Special Variables. ...... 1 12 Figure 24. 

Figure 11- OS Terms and CMS Equivalents. 128 Figure 25, 
Figure 12. CHS Commands That Recognize 

OS Data Sets and OS Disks.... 129 Figure 26. 
Figure 13. Creating CMS Files From OS 

Data Sets.. .................. 136 Figure 27. 

Figure 14. OS Macros Simulated by CMS... .142 Figure 28. 

Figure 29. 



CMS/DOS Commands and CMS 
commands with Special 

Operands for CMS/DOS .153 

DOS/VS Macros Supported by 

CMS .170 

Summary of DEBUG Subcommands. 215 
Comparison of CP and CMS 
Facilities for Debugging. ... .222 

Simplified CHS Storage Map... 224 
Sample CHS Assembler Program 
Entry and Exit Linkage. ..... .240 

A Sample Listing of a 

Program That Uses CMS Macros. 249 

updating Source Files with the 

UPDATE Command 255 

An Update with a Control 

File , .,-.,..-261 

CMS command Summary ...,...-. .328 
CMS Commands for System 

Programmers ,..,.- .332 

CP Privilege Class 

Descriptions. .333 

CP Command Summary.. ......... .334 

3270 Screen Display .343 

HOW the CMS Editor Formats 

a 3270 Screen 345 



Contents 



XI 



( 

xii IBM VM/370 CMS User's Guide 



Sanaary of Amendments 

for GC20-1819-2 

VM/370 Be lease 6 PLC 1 



SOPPRESSION OF PASSWORDS ON THE 
LINE 



COHHAND 



SPICIAL HISSA6E FACILITY 



New: Program Feature 

VM/370 supports a system generation 
option that prevents passwords from 
being entered on the same line as LOGON, 
AUTOLOG, and LINK commands. The 
passwords must be entered so that they 
are not displayed or are masked. This 
support is mentioned where there are 
examples showing the password being 
entered on the same line. 



New: Program Feature 

The special message facility is a method 
of transferring messages from a user to 
a specially programmed receiving virtual 
machine for processing. This support is 
reflected in "Section 3. What You Can Ec 
With VH/370-CMS Commands." 



MISCELLANEOUS 



3278 MODEL 2A DISPLAY STATION 



New: Program Feature 

CP and CMS editor support the 3278 Model 
2A Display Station- This is a 20-line 
display console. Support is reflected 
in "Appendix C. Considerations for 3270 
Display Terminal Users." 



New and Changed: Documentation 

Technical and editorial changes have 
been made throughout this publication. 
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Saiiary of AnendiieDts 

for GC20-1819-1 

as updated by THL GN25-0411 

VB/370 Release 5 PLC 1 



DOS/VS RELEASE 34 SOPPOHTED QOERI DOSLHCNT displays the current 

number of SYSLST lines per page 

New: Progran Feature established by the SET DCSLNCHT. 

CMS/DOS supports DOS/VS Release 34. This release also contains support for 

This support includes a new operand of the 3330 Hodel 11 and 3350 DISD devices 

the SET ccmnand, DOSLNCNT, and a new as attached devices. DCS/VOS Release 3H 

operand of the QUERY coamand, DOSLNCNT. information is contained in "Section 9. 

SET DOSLNCNT allO¥s a user to establish Developing DOS Prograis under CHS." 
the number of SYSLST lines per page. 
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The "Preface" is also updated to 

indicate that the 3704/3705 

Communications Controllers are referred 
to as 370x. 



BOCDMENTATION UPDATE 



Chancied: Documentation Only 

"Section 8. Developing OS Programs 
Under CMS" now includes a description of 
the AUXPROC option that allows the 
FILEDEF command to use an auxiliary 
processing routine to receive control 
during I/O processing. 

"Section 10. Using Access Method 
Services and VSAM" has been rewritten to 
include a description of Data and 
Master-catalog Sharing, Disk 
Compatibility, and VSAM Allocation. 

In addition, minor technical and 
editorial corrections have been made. 



313 Virtual Machine Fac il ity:/37 : 

En V ir on men t al j?££ cr Jecor di na , 
^^iii*^3» JI^J Printi n g (EREP) Program, 
Order~No. GC29-8300 

JSZJEQPggB^gl ^LL£E Recording , 

Editing, and Printing (EREP) Program 
iSaii* Order NoT Slf 25-77 01 

In order to make use of the CPEREP command, 
both of the following publications are 
reguired. The first publication provides 
general information on the usage of the 
command and detailed information on command 
operands applicable only to VM/370- The 
second publication provides detailed 
information on the operands that are common 
to both VM/37C and OS/VS- 

IBM Virtual Machine Facility/320: OLTSEP 
and Error Recording Guide, Order No. 
GC20-1809 

OS/VS Environmental Recording Editing 
and Printing (EREP) Program, Order No. 
GC28~C772 

Program logic information describing the 
interface between CBS and CS/VS EREP, and 
describing OS/VS EREP, is contained in: 

IM Ii£tual Machine Facility/370; 
Service Routines Program Logic, Order 
No. SY 20-0882" 

SS/VS Environmental Recording Editing 
and Priting (EREP) Program Logic, Order 
No. SY28-0773 

The following areas in this publication 
reflect CPEREP documentation changes: 

Preface 
Appendix A 



VM/37C SUPPORTS OS/VS EREP (IFCEREP1) 

Changed: Program and Documentation 

The CPEREP command now uses all edit and 
format operands that are available to 
OS/VS EREP. Because of VM/370s 
compatibility with OS/VS EREP VM/370 
relies en existing OS/VS EREP 
documentation. Therefore, VM/370 no 
longer publishes the following: 
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Part 1. Understanding CMS 



Learniiig how to use CMS is not an end in itself: you have a specific 

task or tasks to do, and you need to use the computer to perform them. 

CMS has been designed to make these tasks easier, but if you are 

unfamiliar with CMS, then the tasks may seem more difficult. The 
information contained in Part 1 of the user's guide is organized to help 

you make the acquaintance of CMS quickly, so that it enhances, rather 
than impedes, the performance of your tasks. 

"Section 1. What It Means To Have a CMS Virtual Machine" introduces 
you to VM/370 and its conversational component, CMS. It should help you 
to get a picture of how you, at a terminal, use and interact with the 
system. 

During a terminal session, commands and requests that you enter are 

processed by different parts of the system. How and when you can 

communicate with these different programs, is described in "Section 2. 
VM/370 Environments and Mode Switching." 

There are almost two hundred commands and subcommands comprising the 
VM/370 language. There are some that you may never need to use; there 
are others that you will use over and over again. "Section 3. What You 
Can Do With VM/370-CMS Commands" contains a sampling of commands in 
various functional areas, to give you a general idea of the kinds of 
things you can do, and the commands available to help you do them. 

Almost every CMS command that you enter results in some kind of 

activity with a direct access storage device (DASD) , known in CMS simply 

as a disk, or minidisk. Data and programs a.re stored on disks in what 

^1 are called "files." "Section 4. The CMS File System" introdudes you to 

the creation and handling of CMS files. 

"Section 5. The CMS Editor" contains all the basic information you 
need to create and write a disk file directly from your terminal, or to 
correct or modify an existing CMS file- 

Just as important as the CMS editor is another CMS facility, called 
the EXEC processor or interpreter. Dsing EXEC files, you can execute 
many commands and programs by entering a single command line from your 
terminal, or you can write your own CMS commands. "Section 6. 
Introduction to the EXEC Processor" presents a survey of the basic 
characteristics and functions of EXEC. 

"Section 7. Using Real Printers, Punches, Readers, and Tapes" 
discusses how to use punched cards and tapes in CMS, and how to use your 
virtual printer and punch to get real output. 
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Section 1. What It Means To Have a CMS 
Virtual Machine 



virtual Machine Pacility/370 (VM/370) is a system control progran that 
controls "virtual machines." A virtual machine is the functional 
equivalent of a real computer, but where the computer has lights, 
buttons, and switches on the real console to control it, you control 
your virtual machine from your terminal, using a command language of 
active verbs and nouns. There are actually three command languages, CP, 
CMS, and RSCS. 

The command languages correspond roughly to the four components of 
VM/370: the Control Program (CP) , the Conversational Monitor System 
(CMS), the Remote Spooling Communications Subsystem (RSCS), and the 
Interactive Problem Control System (IPCS) . CP controls the resources of 
the real machine; that is, the physical machine in your computer room; 
it also manages the communications among virtual machines, and between a 
virtual machine and the real system- CMS is the conversational 
operating system designed specifically to run under CP; it can simulate 
many of the functions of the OS and DOS operating systems, so that you 
can run many OS and DOS programs in a conversational environment. RSCS 
is a subsystem designed to supervise transmission of files across a 
teleprocessing network controlled by CP. IPCS provides system 
programmers and installation support personnel with problem reporting 
and analysis functions. Its commands execute in the CMS command 
environment. 

Although this publication is concerned primarily with using CMS, it 
also contains examples of CP commands that you, as a CMS user, should be 
familiar with. 



How You Communicate with VM/370 

When you are running your virtual machine under VM/370, each command, or 
request for work, that you enter on your terminal is processed as it is 
entered; usually, you enter one command at a time and commands are 
processed in the order that you enter them. 

You can enter CP commands from either the CP or CMS environment; but 
you cannot enter CMS commands while in the CP environment. The concept 
of "environments" in VM/370 is discussed in "Section 2. VM/370 
Environments and Mode Switching." 

After you have typed or keyed in the line you wish to enter, you 
press the Return or Enter key on the keyboard. When you press this key, 
the line you have entered is passed to the command environment you want 
to have process it. If you press this key without entering any data, 
you have entered a "null line." Null lines sometimes have special 
meanings in VM/370. 

If you make a mistake entering a command line, VM/370 tells you what 
your mistake was, and you must re-enter the entire command line. The 
examples in this publication assume that the command lines are correctly 
entered. 

You can enter commands using any combination of uppercase and 
lowercase characters; VM/370 translates your input to uppercase. 
Examples in this publication show all user-entered input lines in 
lowercase characters and system responses in uppercase characters. 
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The CP Command Language 

You use CP commands to communicate with the control program. CP commands 
control the devices attached to your virtual machine and their 
characteristics. 

For example, if you want to allocate additional disk space for a work 
area or if you want to increase the virtual address space assigned to 
your virtual machine, use the CP command DEFINE. CP takes care of the 
space allocation for you and then allows your virtual machine to use it. 

Or if, for example, you are receiving printed output at your terminal 
and do not want to be interrupted by messages from other VM/370 users, 
you can use the CP command SET MSG OFF to refuse messages, since it is 
CP that handles communication among virtual machines. 

Using CP commands, you can also send messages to the VM/370 system 
operator and to other users, modify the configuration of devices in your 
virtual machine, and use the virtual machine input/output devices. CP 
commands are available to all virtual machines using VM/370. You can 
invoke these commands when you are in the virtual machine environment 
using CMS (or some other operating system) in your virtual machine. 

The CP commands and command privilege classes are listed in "Appendix 
B: Summary of CP Commands". The CP Commands applicable to the average 
user are discussed in detail in the VM/370 CP Command Reference for 
General Users. The rest of the CP commands are discussed in VM/370 
Operator's Guide. However, since many CP commands are used with CMS 
commands, some of the CP commands you will use most frequently are 
discussed in this publication, in the context of their usefulness for a 
CMS application. To aid you in distinguishing between CMS commands and 
CP commands, all CP commands used in examples in this publication are 
prefaced with "CP". 



The CMS Command Language 

The CMS command language allows you to create, modify, and debug problem 
or application programs and, in general, to manipulate data files. 

Many OS language processors can be executed under CMS: the assembler, 
VS BASIC, OS FORTRAN IV, OS COBOL, and OS PL/I Optimizing and Checkout 
Compilers. In addition, the DOS/VS COBOL and DOS/VS PL/I Program 
Products are supported. You can find a comprehensive list of language 
processors that can be executed under CMS and relevant publications in 
the VM/370 Introduction. CMS executes the assembler and the compilers 
when you invoke them with CMS commands. The ASSEMBLE command is used to 
present examples in this publication; the supported compiler commands 
are described in the appropriate DOS and OS program product 
documentation. 

The EDIT command invokes the CMS editor so that you can create and 
modify files. The EXEC facilities allow you to execute procedures 
consisting of CP and CMS commands; they also provide the conditional 
execution capability of a macro language. The DEBUG command gives you 
several program debugging subcommands. 

Other CMS commands allow you to read cards from a virtual card 
reader, punch cards to a virtual card punch, and print records on a 
virtual printer. Many commands are provided to help you manipulate your 
virtual disks and files. 
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You use the HELP command to display at your terminal information on 
how to use CP commands and CMS commands, subcommands, and EXECs, and 
explanations of CP and CMS messages. You can issue the HELP command 
when a brief explanation of syntax, a parameter, or function is 
sufficient, thereby avoiding interrupting your terminal session to refer 
to a manual. 
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Since you can invoke CP commands from within the CMS virtual machine 
environment, the CP and CMS command languages are, for practical 
purposes, a single, integrated command language for CMS users. 

GETTING COMMANDS INTO THE SYSTEM 

Before you can use CP and CMS, you should know (1) how to operate your 
terminal and (2) your userid (user identification) and password. 

The Terminal: Your Virtual Console 

There are many types of terminals you can use as a VM/370 virtual 
console. Before you can conveniently use any of the commands and 
facilities described in this publication, you have to familiarize 
yourself with the terminal you are using. Generally, you can find 
information about the type of terminal you are using and how to use it 
with VM/370 in the VM/370 Terminal User_|^s Guide. If your terminal is a 
3767, you also need the IBM 3767 Operator's Guide. 

In this publication, examples and usage notes assume that you are 
using a typewriter-style terminal (such as a 27U1) . If you are using a 
display terminal (such as a 3270), consult "Appendix C: Considerations 
for 3270 Display Terminal Users" for a discussion of special techniques 
that you can use to communicate with VM/370. 

12^ Userid and Password; Ke^s into the System 

Your userid is a symbol that identifies your virtual machine to VM/370 
and allows you to gain access to the VM/370 system. Your password is a 
symbol that functions as a protective device ensuring that only those 
authorized to use your virtual machine can leg on. The userid and 
password are usually defined by the system programmer for your 
installation. 

Contactina VM/370 

To establish contact with VM/370, you switch the terminal device on and 
VM/370 responds with some form of the message 

vm/370 online 

to let you know that VM/370 is running and that you can use it. If you 
do not receive the "vm/370 online" message, see the VM/370 Terminal 
IIser_!^s Guide for specific directions. You can now press the Attention 
key (or equivalent) on your terminal and issue the LOGON command to 
identify yourself to the system: 

cp logon smith 

where SMITH represents a userid. The LOGON command is entered by 
pressing the Return (or Enter) key. If VM/370 accepts your userid, it 
responds by asking you for your password: 

ENTER PASSWORD: 

You then enter your password, which may be hidden, depending on your 
terminal. 
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LOADING CMS IN THE VIRTUAL MACHINE: THE IPL COMMAND 

You load CMS in your virtual machine using the IPL command: 

cp ipl cms 

where "cms" is assumed to be the saved system name for your 
installation's CMS. You could also load CMS by referring to it using 
its virtual device address, such as 190: 

cp ipl 190 

VM/370 responds by displaying a message such as: 

CMS VERSION V.3 - 02/28/76 12:02 

to indicate that the IPL command executed successfully and that CMS is 
loaded into your virtual machine. 

Your userid may be set up for an automatic IPL, so that you receive 
this message, indicating that you are in the CMS command environment, 
without having to issue the IPL command. 

Now you can enter a null line to begin your virtual machine 
operation. 

Note: If this is the first time you are using a new virtual disk 
assigned to you, you receive the message: 

DMSACC112S DISK* A (191) • DEVICE ERROR 

and you must "format" the disk, that is, prepare it for use with CMS 
files. See "Formatting Virtual Disks" below. 



Logical Line Editing Symbols 

To aid you in entering command or data lines from your terminal, VM/370 
provides a set of logical line editing symbols, which you can use to 
correct mistakes as you enter lines. Each symbol has been assigned a 
default character value. These normally are: 

Symbol Character 
Logical character delete S 
Logical line end # 

Logical line delete t 
Logical escape " 

I;2£ic^i Character Delete 

The logical character delete symbol (S) allows you to delete one or more 
of the previous characters entered. The 3 deletes one character per a 
entered, including the t and # logical editing characters. For example: 

ABC#aS results in AB 
ABCSD results in A ED 
0SDEF results in DEF 
ABCasS deletes the entire string 
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Logical Line End 

The logical line end symbol (#) allows you to key in more than one 
command on the same line, and thus minimizes the amount of time you have 
to wait between entering commands. You type the # at the end of each 
logical command line, and follow it with the next logical command line. 
VM/370 stacks the commands and executes them in sequence. For example, 
the entry: 

query bliptquery rdymsgtquery search 

is executed in the same way as the entries: 

query blip 
query rdymsg 
query search 

The logical line end symbol also has special significance for the #CP 
function. Beginning any physical line with #CP indicates that you are 
entering a command that is to be processed by CP immediately. If you 
have set a character other than # as your logical line end symbol, you 
should use that character instead of a #. 

Ij2SLical Line Delete 

The logical line delete symbol ((«) (or [ for Teletype* Model 33/35 
terminals) deletes the entire previous physical line, or the last 
logical line back to (and including) the previous logical line end (#) . 
You can use it to cancel a line containing many or serious errors. If a 

# immediately precedes the sign, only the # sign is deleted, since the 

# indicates the beginning of a new line, and the cancels the current 
line. For example: 

• Logical Line Delete: 

ABC#DEF0 deletes the #DEF and results in ABC 
ABC#0 results in ABC 
ABC#DEF0#GHI results in ABC#GHI 
ABC#DEF0GHI results in ABCGHI 

• Physical Line Delete: 

ABCj^ deletes the whole line 

Note that when you cancel a line by using the logical line delete 
symbol, you do not need to press a carriage return; you can continue 
entering data on the same line. 

Logical Escape 

The logical escape symbol (") causes VM/370 to consider the next 
character entered to be a data character, even if it is normally one of 
the logical line editing symbols (9, «J, ", or #) . For example: 

ABC"0D results in ABC^D 
""ABC"" results in "ABC" 



^Trademark of the Teletype Corporation, Skokie, Illinois. 
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If you enter a single logical escape symbol {") as the last character 
on a line, or on a line by itself, it is ignored. 

Hhen you enter logical escape characters in conjunction with other 
logical editing characters, the results may be difficult to predict. 
For example, the lines: 

ABC""SDEF 
ABC""SaDEF 

both result in the line: 

ABCDEF 



Defining Logical Line Editing Symbols 

The logical line editing symbols are defined for each virtual machine 
during VM/370 system generation. If your terminal's keyboard lacks any 
of these special characters, your installation can define other special 
characters for logical line editing. You can find out what logical line 
editing symbols are in effect for your virtual machine by entering the 
command: 

cp query terminal 

The response might be something like: 

LINEND # , LINEDEL t. , CHARDEL 3 , ESCAPE " 
LINESIZE 130, MASK OFF, APL OFF, ATTN OFF, MODE VM 

You can use the CP TERMINAL command to change the logical line ^ 
editing characters for your virtual machine. For example, if you enter: \i 

cp terminal linend / 
Then, the line: 

input # line / input / # 

would be interpreted: 

input # line 
input 
# 

The terminal characteristics listed in the response to the CP QUERY 
TERMINAL command are all controlled by operands of the CP TERMINAL 
command. 



HOH VM/370 RESPONDS TO YODR COMMANDS 

CP and CMS respond differently to different types of requests. All CMS 
command responses (and all responses to CP commands that are entered 
from the CMS environment) are followed by the CMS ready message. The 
form of the ready message can vary, since it can be changed using the 
SET command. The long form of the ready message is: 



R; T=7. 36/19. 89 09:26:11 
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If you have issued the command: 

set rdymsg smsg 
the ready message looks like: 

R; 

When you enter a command line incorrectly, you receive an error 
message, describing the error. The ready message contains a return code 
from the command; for example: 

R (00028) ; 

indicates that the return code from the command was 28. 

Some Sample CP and CMS Command Responses 

If you enter a CP or CMS command that requests information about your 
virtual machine, the response should be the information requested. For 
example, if you issue the command: 

cp display g 

CP responds by showing you the contents of your virtual machine*s 
general registers, for example: 

GPR = 00000003 000O33U0 000007A0 00000003 
GPR 4 = 00000848 C4404040 00000040 00002DF0 
GPR 8 = 00000008 000132F8 00002BA0 00002230 
GPR 12 = 00003238 FFFFFFFD 50013386 00000000 

Similarly, if you issue the CMS command: 

listfile * assemble c 

you might receive the following information: 

JUNK ASSEMBLE C1 
MYPROG ASSEMBLE Cl 

If you enter a CP command to alter your virtual machine configuration 
or the status of your spool files, CP responds by telling you that the 
task is accomplished. The response to: 

cp purge reader all 

might be: 

0004 FILES PURGED 

Some CP commands, those that alter some of the characteristics of 
your virtual machine, give you no response at all. If you enter: 

cp spool e class x hold 

you receive no response from CP. 

Certain CMS commands may issue prompting messages, to request you to 
enter more information. The SORT command, which sorts CMS disk files^ 
is an example. If you enter: 

sort in file a1 out file a1 

Section 1. What it Means to Have a CMS Virtual Machine 9 



March 30, 1979 

you are prompted with the message: 

DMSSRT604R ENTER SORT FIELDS: 

and you can then specify which fields you wish the input records to be 
sorted on. 



Getting Acquainted with CMS 

If you have just logged on for the first time, and you want to try a few 
CHS commands, enter: 

query disk a 

The response should tell you that you have an A-disk at virtual address 
191; it also provides information such as how much room there is on the 
disk and how much of it is used. Again, if you receive an error message 
that indicates the disk may not be formatted, see "Formatting Virtual 
Disks." 

Your A-disk is the disk you use most often in CHS, to contain your 
CMS files. Files are collections of data, and may have many purposes. 
For this exercise, the data is meaningless. Enter: 

edit junk file 

You should receive the response: 

NEW FILE: 
EDIT: 

which indicates that this file does not already exist on your A-disk. 
Enter: 

input 

You should receive the response: 

INPUT: 

and you can start to create the file, that is, write input records that 
are eventually going to be written onto your A-disk. Enter 5 or 6 data 
lines, such as: 

hickory dickory dock 
the mouse ran up the clock 
the clock struck one 
and down he run 
dickory hickory dock 

Now, enter a null line (one with no data) - You should receive the 
message: 

EDIT: 
Enter: 

file 
You should see the message: 

R; T=0. 01/0.02 19:31:29 
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You have just written a CMS file onto your A-disk. If you enter: 

type junk file a 

you should see the following: 

HICKORY DICKORY DOCK 

THE MOUSE RAN OP THE CLOCK 

THE CLOCK STRUCK ONE 

AND DOWN HE RUN 

DICKORY HICKORY DOCK 

The CMS command, TYPE, requested a display of the disk file JUNK FILE, 
on your A-disk. 

To erase the file, enter: 

erase junk file 

Now, if you re-enter the TYPE command, you should receive the message: 

FILE NOT FOUND 

Most CMS commands create or reference disk files, and are as easy to 
use as the commands shown above. Your CMS disks are among the most 
important features in your VM/370 virtual machine. 

Virtual Disks and How They Are Defined 

Under VM/370, a real direct access storage device (DASD) unit (disk 
pack) or an FB-512 device can be divided into many small areas, called 
minidisks. Minidisks (also called virtual disks because they are not 
equivalent to an entire real disk) are defined in the VM/370 directory, 
as extents on real disks. For CMS applications, you never have to be 
concerned with the extents on your minidisks; when you use CMS-f ormatted 
minidisks, they are, for practical purposes, functionally the same as 
real disks. Minidisks can also be formatted for use with OS or DOS data 
sets or VSAM files. 

You can have both permanent and temporary disks attached to your 
machine during a terminal session. Permanent disks are defined in the 
VM/370 directory entry for your virtual machine. Temporary disks are 
those you define for your own virtual machine using the CP DEFINE 
command, or those attached to your virtual machine by the system 
operator. 

PERMANENT VIRTUAL DISKS 

The VM/370 directory entry for your userid defines your permanent 
virtual disks. Each disk has associated with it an access mode 
specifying whether you can read and write on the disk or only read from 
it (its read/write status) . Virtual disk entries in the VM/370 
directory may look like the following: 



MDISK 


190 


2314 


000 


050 


CMS190 


R 


MDISK 


191 


3330 


010 


005 


BDISKE 


H 


MDISK 


194 


3330 


010 


020 


CMS001 


W 


MDISK 


195 


FB-512 


1000 


500 


FBDISK 


W 


MDISK 


198 


3330 


050 


010 


CMS192 


H 


MDISK 


19E 


3330 


010 


050 


CMS19E 


R 
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The first two fields describe the device, minidisk in this example, 
and the virtual address of the device. Virtual addresses (shown above 
as 190, 191, and so on), are the names by which you and VM/370 identify 
the disk. Each device in your virtual machine has an address which may 
or may not correspond to the actual location of the device on the VB/370 
system. 

I The third field specifies the device type of your virtual disk. For 

I count-key-data devices, the fourth and fifth fields specify the starting 

real cylinder at which your virtual disk logically begins and the number 

I of cylinders allocated to your virtual disk, respectively. For FB-512 

I devices, the fourth field specifies the starting real block numbers 

I where your virtual disk begins, and the fifth field is the number of 

I blocks allocated to your virtual disk. The sixth field is the label of 

the real disk on which the virtual disk is defined and the seventh field 

is a letter specifying the read/write mode of the disk; "R" indicates 

that the disk is a read-only disk, and "W" indicates that you have 

read/write privileges. The MDISK control statement of the Directory 

Service Program is described in the VM/370 Operator *s Guide. 



DEFINING TEMPORARY VIRTUAL DISKS 

Using the CP DEFINE command, you can attach a temporary disk to your 
virtual machine for the duration of a terminal session. The following 
command allocates a 10-cylinder temporary disk from a 3330 device and 
assigns it a virtual address of 291: 

cp define t3330 as 291 cyl 10 

When you define a minidisk, you can choose any valid address that is not 
already assigned to a device in your virtual machine. Valid addresses 
for minidisks range from 001 through 5FF, for a virtual machine in basic 
control mode. 

FORMATTING VIRTUAL DISKS 

Before you can use any new virtual disk, you must format it. This 
applies to new disks that have been assigned to you and to temporary 
disks that you have allocated with the CP DEFINE command. When you 
issue the FORMAT command you must use the virtual address you have 
defined for the disk and assign a CMS mode letter, for example: 

format 291 c 

CMS then prompts you with the following message: 

DMSFOR603R FORMAT WILL ERASE ALL FILES ON DISK •C(291)«. DO YOU 
WISH TO CONTINUE? (YES | NO): 

You respond: 

yes 

CMS then asks you to assign a label for the disk, which may be anything 
you choose. Labels can have a maximum of 6 characters. When the 
message: 

DMSFOR605R ENTER DISK LABEL: 
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is issued, you respond by supplying a disk label. For example, if this 
is a temporary disk, you might enter: 

scrtch 
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CMS then erases all the files on that disk, if any existed, and formats 
the disk for your use. When you enter the label, CMS responds by 
telling you: 

FORMATTING DISK 'C 



•10» CYLINDERS FORMATTED ON 'C(291)«. 

R; T=0. 15/1.60 11:26:03 

The FORMAT command should only be used to format CMS disks, that is, 
disks you are going to use to contain CMS files. If you want to format 
I count-key-data disks for OS, DOS, or VSAM applications, the disks should 
be formatted using the IBCDASDI program. 

The FORMAT command allows a choice of physical disk block size as an 
option- See the VM/370 CMS Command and Macro Reference for details. To 
format FB-512 disks for OS, DOS, or VSAM applications, the disks can be 
formatted using the INTDK stand-alone utility program. See VM/370 
Operator* s Guide for details. 



Sharing Virtual Disks: Linking 

Since only one user can own a virtual disk, and there are many occasions 
that require users to share data or programs, VM/370 allows you to share 
virtual disks, on either a permanent or temporary basis, by "linking." 

Permanent links can be established for you in your VM/370 directory 
entry. These disks are then a part of your virtual machine 
configuration every time you log on. 

You can also have another user»s disk temporarily added to your 
configuration by using the CP LINK command. For example, if you have a 
program that uses data that resides on a disk identified in userid 
DATA'S configuration as a 194, and you know that the password assigned 
to this disk is GO, you could issue the command: 

cp link to data 194 as 198 r pass= go* 

DATA'S 194 disk is then added to your virtual machine configuration at 
virtual address 198. 

The "R" in the command line indicates the access mode; in this case, 
it tells CP that you wish only to read files from this disk. VM/370 
will not allow you to write on it. If you try to issue this command 
when someone is logged on to the userid DATA, you will not be able to 
establish the link. If you want to link to DATA in any event, you can 
reissue the LINK command using the access mode RR: 

cp link data 194 198 rr go* 

The keywords TO, AS, and PASS= are optional; you do not have to specify 
them. 

You can also use the CP LINK command to link to your own disks. For 
example, if you log on and discover that another user has access to one 
of your disks, you may be given read-only access, even if it is a 
read/write disk. You can request the other user to detach your disk 



*Note that the password cannot be entered on the command line if the 
password suppression facility was specified at sysgen. 



Section 1. What it Means to Have a CMS Virtual Machine 13 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8 

from his virtual machine, and after he has done so, you can establish 
the link: 

cp link * 191 191 

When you link to your own disks, you can specify the userid as * and you 
do not need to specify the access mode or a password. 

You can find more information about the CP LINK command and CP access 
modes in YM^370 CP Command Reference for General Users. 



Identifying Your Disk to CMS: Accessing 

LINK and DEFINE are CP commands: they tell CP to add DASD devices to 
your virtual machine configuration. CMS must also know about these 
disks, and you must use the ACCESS command to establish a filemode 
letter for them: 

access 194 b 

CMS uses filemode letters to manage your files during a terminal 
session. By using the ACCESS command you can control: 

• Whether you can write on a disk or only read from it (its read/write 
status) 

• The library search order for programs executing in your virtual 
machine 

• Which disks are to contain the new files that you create 

If you want to know which disks you currently have access to, issue 
the command: 

query search 

You might see the following display: 

PER191 191 A R/W 

DAT19U 198 B R/0 

CMS 190 190 S R/0 

CMS19E 19E Y R/0 

The first column indicates the label on the disk (assigned when the disk 
is formatted) , and the second column shows the virtual address assigned 
to it. 

I The third column contains the filemode letter. All letters of the 
I alphabet are valid filemode letters. 

The fourth column indicates the read/write status of the disk- The 
190 and 19E disks in this example are read-only disks that contain the 
I CMS nucleus and disk-resident commands for the CMS system. You will 
I probably use your 191 (A) disk as your primary read/write work disk. 



14 IBM VM/370 CMS User's Guide 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 57t»8-XX8 

RELEASING VIRTOAL DISKS 

When you no longer need a disk during a terminal session, or if you want 
to assign a currently active filemode letter to another disk, use the 
CHS command RELEASE: 

release c 

Then, you can issue the ACCESS command to assign the filemode letter C 
to another disk. 
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When you no longer need disks in your virtual nachine configuration, 
use the CF command DETACH to disconnect them from your virtual machine: 

cp detach 194 
cp detach 291 

If you are going to release and detach the disk at the same time, you 
can use the DET option of the RELEASE command: 

release 19U (det 

For more information on controlling disks in CMS, see "Section 4. The 
CMS File System." 



I 
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Section 2. VM/370 Environments and Mode 
Switching 



When yoa are using VM/370, your virtual machine can be in one of two 
possible "environments": the CP, or control program environment, or the 
virtual machine environment, which may be CMS. The CMS environment has 
several subenvironments, sometimes called "modes." Each environment or 
subenvironment accepts particular commands or subcommands, and each 
environment has its own entry and exit paths, responses and error 
messages. If you have a good understanding of how the VM/370 
environments are related, you can learn to change environments quickly 
and use your virtual machine efficiently. 

This section introduces the CP and CMS environments that you use and 
describes: 

• Entry and exit paths 

• Command subsets that are valid as input 

Figure 1, at the end of this section, summarizes the VM/370 command 
environments and lists the commands and terminal paths that allow you to 
go from one environment to another. 

With the exception of input mode in the edit environment, you can 
always determine which environment your virtual machine is in by 
pressing the Return or Enter key on a null line. The responses you 
receive and the environments they indicate, are: 

Response Isvironment 

CP CP 

CMS CMS 

CMS (DOS ON) CMS/DOS 

EDIT: Edit 

CMS SUBSET CMS Subset 

DEBUG Debug 



The CP Environment 

When you log on to VM/370, your virtual machine is in the CP 
environment. In this environment, you can enter any CP command that is 
valid for your privilege class. This publication assumes that you are a 
general, or class G, user. You can find information about the commands 
that you can use in the VM/370 CP Command Reference for General Users. 

Only CP commands are valid terminal input in the CP environment. You 
can, however, preface a CP command line with the characters "CP" or 
"#CP", followed by one or more blanks, although it is not necessary. 
These functions are described under "The CMS Environment." 

YOU can enter CP commands from other VM/370 environments. There may 
be times during your terminal session when you want to enter the CP 
environment to issue one or more CP commands. You can do this from any 
other environment by doing either of two things: 

1. Issue the command: 

#cp 
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2. OsG your terminal's Attention key (or equivalent). On a 2741 
terminal, you must normally press the Attention key twice, quickly, 
to enter the CP environment. 

The following message indicates that your virtual machine is in the CP ( 
environment: 

CP 

After entering whatever CP commands you need to use^ you return your 
virtual machine to the environment or mode that it came from by using 
the CP command: 

cp begin 

which, literally, begins execution of your virtual machine. 

The CMS Environment 

You enter the CMS environment from CP by issuing the IPL command, which 
loads CMS into your virtual storage area. If you are planning to use 
CMS for your entire terminal session^ you should not have to IPL again 
unless a program failure forces you into the CP environment. 

When you issue the IPL command, you can specify either the named 
system CMS at your installation or you can load CMS by specifying the 
virtual address of the disk on which the CMS system resides. For 
example: 

cp ipl cms 

— or — 

cp ipl 190 ^ 

When your virtual machine is in the CMS environment, you can issue 
any CMS command and any of the CP commands that are valid for your user 
privilege class. You can also execute many of your own OS or DOS 
programs; the ways you can execute programs are discussed in "Section 8. 
Developing OS Programs Under CMS" and "Section 9. Developing DOS 
Programs Under CMS." 

You can enter CP commands from CMS in any of the following ways: 

• Using the implied CP function of CMS (See Note.) 

• With the CP command 

• With the #CP function 

Note: For the most part, you may enter any CP command directly from 
the CMS environment. This implied CP function is controlled by an 
operand of the CMS SET command, IMPCP. You can determine whether the 
implied CP function is in effect for your virtual machine by entering 
the command: 

query impcp 
If the response is: 

IMPCP = OFF 
you can change it by entering: 

set impcp on M 
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When the implied CP function is set off, you must use either the 
CP command or the #CP function to enter CP commands from the CMS 
environment. CP commands that you execute in EXEC procedures must 
always be prefaced by the CP command, regardless of the implied CP 
setting. An example of using the CP command is: 

cp close punch 

When you issue CP commands from the CMS environment either 
implicitly or with the CP command, you receive, in addition to the CP 
response (if any) , the CMS ready message. If you use the #CP 
function, discussed next, you do not receive the ready message. 

You can preface any CP command line with the characters "#CP", 
followed by one or more blanks. When you enter a CP command this 
way, the command is processed by CP immediately; it is as if your 
virtual machine were actually in the CP environment. 



EDIT, INPUT, AND CMS SUBSET 

The CMS editor is a VM/370 facility that allows you to create and 
modify data files that reside on CMS disks. The editor environment, 
more commonly called the edit environment, is entered when you issue 
the CMS command EDIT, specifying the identification of a data file 
you want to create or modify. 

edit myfile assemble 

is an example of how you would enter the edit environment to either 
create a file called MYFILE ASSEMBLE or to make changes to a disk 
file that already exists under that name. 

When you enter the edit environment your virtual machine is 
automatically in edit mode, where you can only issue EDIT subcommands 
or CP commands prefaced by "#CP." EDIT subcommands tell the editor 
what you wish to do with the data you have accessed. After you enter 
the EDIT subcommand: 

input 

data lines that you enter are considered input to the file. To 
return to edit mode, you must enter a null line. 

If you issue the EDIT subcommand: 

cms 

the editor responds: 

CMS SUBSET 

and your virtual machine is in CMS subset mode, where you can issue 
any valid CMS subset command, that is, a CMS command that is allowed 
in CMS subset mode. These include: 

ACCESS 

CP 

DISK 

ERASE 

EXEC 

HT 
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LISTFILE 


RT 


PRINT 


SET 


PUNCH 


STATE 


QUERY 


STATEW 


READCARD 


TYPE 



You can also issue CP commands. To return to edit mode, you use 
the special CMS subset command, RETORN. If you enter the Immediate 
command HX, your editing session is terminated abnormally and your 
virtual machine is returned to the CMS environment. 

When you are finished with an edit session, you return to the CMS 
environment by issuing the FILE subcommand, which indicates that all 
modifications or data insertions that you have made should be written 
onto a CMS disk, or by issuing the subcommand QUIT, which tells the 
editor not to save any modifications or insertions made since the 
last time the file was written. 

More detailed information about EDIT subcommands and how to use 
the CMS editor is contained in this publication in "Section 5. The 
CMS Editor" and in the VM/370 CMS Command and Macro Reference. 



DEBUG 

CMS DEBUG is a special CMS facility that provides subcommands to help 
you debug programs at your terminal. Your virtual machine enters the 
debug environment when you issue the CMS command: 

debug 

You may want to enter this command after you have loaded a program 

into storage and before you begin executing it. At this time you can 

set "breakpoints," or address stops, where you wish to halt your 

program's execution so that you can examine and change the contents 

of general registers and storage areas. When these breakpoints are 

encountered, your virtual machine is placed in the debug environment. 

You can also enter the debug environment by issuing the CP EXTERNAL / 

command, which causes an external interrupt to your virtual machine. \i 

this environment 



Valid DEBUG 


su 


bcommands 


that 


you 


can enter in 


are: 












BREAK 




GO 






RETURN 


CAW 




GPR 






SET 


CSW 




HX 






STORE 


DEFINE 




ORIGIN 






X 


DUMP 




PSW . 









You can also use the #CP function in the debug environment to enter 
CP commands. 

YOU leave the debug environment in any of the following ways: 

If the program you are running completes execution, you are returned 
to the CMS environment. 

If your virtual machine entered the debug environment after a 
breakpoint was encountered, it returns to CMS when you issue the 
DEBUG subcommand: 

hx 

To continue the execution of your program, you use the DEBUG 
subcommand: 

go 
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If your virtual machine is in the debug environment and is not 
executing a program, the DEBUG subcommand: 

return 

returns it to the CMS environment. 



CMS/DOS 



If you are a DOS/VSE user, the CMS/DOS environment provides you with all 
the CMS interactive functions and facilities, as well as special CMS/DOS 
commands which simulate DOS functions. The CMS/DOS environment becomes 
active when you issue the command: 

set dos on 

When your virtual machine is in the CMS/DOS environment you can issue 
any command line that would be valid in the CMS environment, including 
the facilities of EDIT, DEBUG, and EXEC, but excluding CMS commands or 
program modules that load and/or execute programs that use OS macros or 
functions. 



The following commands are provided in CMS/DOS to test 
DOS programs, and to provide access to DOS/VS libraries: 



and develop 



ASSGN 

DLBL 

DOSLIB 

DOSLKED 

DOSPLI 



DSERV 

ESERV 

FETCH 

FCOBOL 

LISTIO 



OPTION 
PSERV 
RSERV 
SSERV 



Your virtual machine leaves the CMS/DOS environment when 
command: 



you issue the 



set dos off 

If you reload CMS (with an IPL command) during a terminal session, you 
must also reissue the SET DOS ON command. 



Interrupting Program Execution 



When you are executing a program under CMS or executing a CMS command, 
your virtual machine is not available for you to enter commands. There 
are, however, ways in which you can interrupt a program and halt its 
execution, either temporarily, in which case you can resume its 
execution, or permanently, in which case your virtual machine returns to 
the CMS environment. In both cases, you interrupt execution by creating 
an "attention interruption," which may take two forms: 

• An attention interruption to your virtual machine operating system 

• An attention interruption to the control program 

These situations result in what are known as virtual machine (VM) or 
control program (CP) "reads" being presented to your virtual console. 
On a typewriter terminal, the keyboard unlocks when a read occurs. 
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Whether you have to press the Attention key once or twice depends on 
the terminal mode setting in effect for your virtual machine. This 
setting is controlled by the CP TERMINAL command: 

cp terminal mode vm 

The setting VM is the default for virtual machines; you do not need to 
specify it. The VM setting indicates that one depression of the 
Attention key sends an interruption to your virtual machine, and that 
two depressions results in an interruption to the control program (CP) . 

The CP setting for terminal mode, which is the default for the system 
operator, indicates that one depression of the Attention key results in 
an interruption to the control program (CP). If you are using your 
virtual machine to run an operating system other than CMS, you might 
wish to use this setting. Issue the command: 

cp terminal mode cp 



VIRTUAL MACHINE INTERRUPTIONS 



While a command or program is executing, if you press the Attention key 
once on a 2741 (or the Enter key on a 3270), you have created a virtual 
machine interruption. The program halts execution, your terminal will 
accept an input line, and you may: 



Terminate the execution of 
command to halt execution: 



the program by issuing an Immediate 



hx 

The HX command causes the program to abnormally terminate (abend) . 

Enter a CMS command. The command is stacked in a console buffer and 
is processed by CMS when your program is finished executing and the 
next virtual machine read occurs- For example: 

print abc listing 

After you enter this line, the program resumes execution. 

If the program is directing output to your terminal and you wish only 
to halt the terminal display, use the Immediate command: 

ht 

The program resumes execution. Terminal output can also be 
suppressed immediately when you enter a command by placing #HT at the 
end of the command line. The logical line end character (#) allows 
the Immediate command HT to be accepted; program execution proceeds 
without typing. 

You can, if you want, cause another interruption and request that 
typing be resumed by entering the RT (resume typing) command: 

rt 

Enter a null line; your program continues execution. The null line is 
stacked in the console stack and read by CMS as a stacked command 
line. 
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HX, HT, and RT are three of the CMS Immediate commands. They are 
"immediate" because they are executed as soon as they are entered. 
Unlike other commands, they are not stacked in the console buffer. You 
can only enter an Immediate command following an attention interruption. 



CONTROL PROGRAM INTERRUPTIONS 

You can interrupt a program and enter the CP environment directly by 
pressing the Attention key twice quickly, on a 2741, or pressing the PAl 
key on a 3270. Then, you can enter any CP command. To resume the 
program's execution, issue the CP command: 

cp begin 

If your terminal is operating with the terminal mode set to CP, pressing 
the Attention key once places your virtual machine in the CP 
environment. 



ADDRESS STOPS AND BREAKPOINTS 

A program may also be interrupted by an instruction address stop, which 
you specifically set by the CP command ADSTOP. For example, if you 
issue the command: 

cp adstop 20 lea 

an address stop is set at virtual storage location X»201EA'. When your 

program reaches this address during its execution, it is interrupted and 

\ your virtual machine is placed in the CP environment, where you can 

/ issue any CP command, including another ADSTOP command, before resuming 

your program's execution with the CP command BEGIN. 

Breakpoints, similar to address stops, are set using the DEBUG 
subcommand BREAK, which you issue in the debug environment before 
executing a program. For example, if you issue: 

break 1 201ae 

Your program's execution is interrupted at this address and your virtual 
machine is placed in the debug environment. You can then enter any 
DEBUG subcommand. To resume program execution, use the DEBUG subcommand 
GO. If you want to halt execution of the program entirely, use the 
DEBUG subcommand HX, which returns your virtual machine to the CMS 
environment. You can find more information about setting address stops 
and breakpoints in "Section 11. How VM/370 Can Help You Debug Your 
Programs." 
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Notes : 

'The CP environment may be entered from any other environment either by using 

your terminal's Attention key or equivalent, or by entering the command #CP. 
^ Any CP command is any CP command that is valid for your user privilege class. 

Any time that a CP command can be entered, it may be prefaced virith #CP. 
^The BEGIN command returns your virtual machine to the environment it was in 

when CP was entered: 

*lf you were in edit or input mode, the current line pointer remains unchanged. 

*lf you were executing a program, execution resumes at the instruction address 
indicated in the PSW. 



Figure 1. VM/370 Environments and Mode Switching 
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Section 3. What You Can Do with 
VM/370-CMS Commands 



This section provides an overview of the CMS and CP command languages, 
and describes the various commands within functional areas, with 
examples. The commands are not presented in their entirety, nor is a 
complete selection of commands represented. 

When you finish reading this section you should have an understanding 
of the kinds of commands available to you, so that when you need to 
perform a particular task using CMS you may have an idea of whether it 
can be done, and know what command to reference for details. For 
complete lists of the CP and CMS commands available, see "Appendix A: 
Summary of CMS Commands" and "Appendix B: Summary of CP Commands." 



Command Defaults 

Many of the characteristics of your CMS virtual machine are already 
established when you log on, but there are commands available so you can 
change them. In the case of many CMS commands, there are implied values 
for operands, so that when you enter a command line without certain 
operands, values are assumed for them. In both of these instances, the 
values set or implied are considered default values. As you learn CP 
and CMS commands, you also should become familiar with the default 
values or settings for each. 

/ Commands to Control Terminal Communications 

Using VM/370, you control your virtual machine directly from your 
terminal. VM/370 provides a set of commands for terminal 
communications. 



ESTABLISHING AND TERMINATING COMMUNICATIONS WITH VM/370 

To initiate your communication with VM/370, use the CP LOGON command: 

cp logon sam 
optionally, you may enter your password on the same line*: 

cp logon sam 123456 

When you are sure that your communication line is all right and you have 
difficulty logging on (for example, someone else has logged on under 
your userid) , you can use the CP MESSAGE command: 

cp message sam this is sam... pis log off 



I iNote that the password cannot be entered on the command line if the 
I password suppression facility was specified at sysgen. 
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Another way to access the VM/370 system is to use the CP command 
DIAL: 

cp dial tsosys 

In this example, TSOSYS is the userid of a virtual machine running a TSO 
system. After this DIAL command is successful, you can use your 
terminal as if you were actually connected to a TSO system, and you can 
begin TSO logon procedures. 

To end your terminal session, use the CP command LOGOFF: 

cp logoff 

If you have used a switched (or dial-up) communication path to the 
VM/370 computer and you want the line to remain available, you can 
enter: 

cp logoff hold 

At times, you might be running a long program under one userid and wish 
to use your terminal for some other work. Then, you can disconnect your 
terminal: 

cp disconn 

— or — 

cp disconn hold 

Your virtual machine continues to run, and is logged off the system when 
your program has finished executing. If you want to regain terminal 
control of your virtual machine after disconnecting, log on as you would 
to initiate your terminal session. Your virtual machine is placed in 
the CP environment, and to resume its execution, you use the CP command 
BEGIN. 

You should not disconnect your virtual machine if a program requires 
an operator response, since the console read request cannot be 
satisfied. 



CONTROLLING TERMINAL OUTPUT 



During the course of a terminal session, you can receive many kinds of 
messages from VM/370, from the system operator, from other users, or 
from your own programs. You can decide whether or not you want these 
messages to actually reach you. For example, if you use the command: 

cp set msg off 

no one will be able to send messages to you with the CP MESSAGE command; 
if another virtual machine user tries to send you a message, he receives 
the message: 

userid NOT RECEIVING, MSG OFF 

I If your virtual machine handles special messages and you do not want to 
I receive special messages at this time, you can issue: 



cp set smsg off 
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NO one will be able to send special messages to you with the CP SMSG 
command; if another virtual machine user attempts to do so, he receives 
a message: 

userid NOT RECEIVING, SMSG OFF 

Similarly, you can use: 

cp set wng off 

to prevent warning messages (which usually come from the system 
operator) from coming to you- You would probably do this, however, only 
in cases where you were typing some output at your terminal and did not 
want the copy ruined. 

VM/370 issues error messages whenever you issue a command incorrectly 
or if a command or prograin fails. These messages have a long form, 
consisting of the error message code and number, followed by text 
describing the error. If you wish to receive only the text portion of 
messages with severity codes I, E, and W (for informational, error, and 
warning, respectively) , you can issue the command: 

cp set emsg text 

If you want to receive only the message code and number (from which you 
can locate an explanation of the error in VM/370 System Messages) , you 
specify: 

cp set emsg code 

You can also cancel error messages completely: 

cp set emsg off 

To restore the EMSG setting to its default, which is the message text, 
enter: 

cp set emsg text 

Some CP commands issue informational messages telling you that CP has 
performed a particular function. You can prevent the reception of these 
messages with the command: 

cp set imsg off 
or restore the default by issuing: 

cp set imsg on 
The setting of EMSG applies to CMS commands as well as to CP commands. 

You can also control the format of the CMS ready message. If you 
enter: 

set rdymsg smsg 

you receive only the "R;" or shortened form of the ready message after 
the completion of CMS commands. If you are not receiving error messages 
L (as described above) and an error occurs, the return code from the 
P command still appears in parentheses following the "R". 
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An additional feature exists for CMS. If you have a typewriter 
terminal with a two-color ribbon, you can specify: 

set redtype on 

so that CMS error messages are typed in red. 

Some commands or messages result in displays of lines that are very 
long. If you want to limit the width of lines that are received at your 
terminal (for example, if you are using terminal paper that is only 
eight inches wide) , you can specify: 

cp terminal linesize 80 

so that all lines received at your terminal are formatted to fit within 
an 80- character display. 

You can also control two special characters in VM/370. One is the 
exclamation point (I) that types when the Attention key is pressed. If 
you do not want this character to type when you press the Attention key, 
use the command: 

cp terminal attn off 

CMS allows you to specify a "blip" character: this character is typed 
or displayed whenever two seconds of processor time are used by your 
virtual machine. If you enter: 

set blip * 

then, during program execution, this character types for every two 
seconds of CPU time. You can cancel the function: 

set blip off 

or set it to nonprintable characters: 

set blip on 

When this command has been entered on a typewriter terminal, the 
Selectric type ball tilts and rotates whenever a blip character is 
received. 

Note: Issuance of the STIMER macro for more than two seconds will mask 
off blips. 

On a display terminal, you can control the intensity of the redisplay 
of user input. If you enter: 

cp terminal hilight on 

the redisplay of user input is highlighted. If you enter: 

cp terminal hilight off 

the redisplay of user input is at normal intensity. This is the 
default. 
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COMMANDS TO CONTROL HOW VM/370 PROCESSES INPOT LINES 

You can manipulate VM/370' s logical line editing function to suit your 
own needs. In addition to using the CP TERMINAL connand to change the 
default logical line editing symbols, you can issue: 

cp set linedit off 
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so that none of the symbols are recognized by VM/370 when it interprets 
your input lines. 

When you are in the CMS environment, there are a number of commands 
that you can use to control how CMS validates a command line. The SET 
command functions IMPCP (implied CP) and IMPEX (implied EXEC) control 
the recognition of CP commands and CMS EXEC procedures. For example, if 
you issue: 

set impcp off # set impex off 

then, when you enter CP commands in CMS or try to execute EXEC 
procedures, you must preface the name of the command or procedure with 
CP (or #CP) , or EXEC, respectively. 

By using the SYNONYM and the SET ABBRE7 commands, you can control 
what command names, synonyms, or truncations are valid in CMS. For 
example, you could set up a file named MYSYN SYNONYM which contains the 
following records: 

PRINT PRT 1 

RELEASE LETGOOF 5 

ACCESS GET 1 

DOSLKED LNKEDT 3 

The first column specifies an existing CMS command, module, or EXEC 
name; the second column specifies the alternate name, or synonym, you 
want to use; and the third column is a count field that indicates the 
minimum number of characters of the synonym that can be used to truncate 
the name. Using this file, after you enter the command: 

synonym mysyn 

you can use PRT, LETGOOF, GET, and LNKEDT in place of the corresponding 
CMS command names. Also, if the ABBREV function is in effect, (it is 
the default; you can make sure it is in effect by issuing the command 
SET ABBREV ON) , you can truncate any of your synonyms to the minimum 
number of characters specified in the count field of the record (that 
is, you could enter "p" for PRINT, "letgo" for RELEASE, and so on) . 

You can set up EXEC files with the same names as CMS commands, that 
may or may not perform the same function as the CMS names they 
duplicate. For example, if every time you used the GLOBAL command you 
used the same operands, you could have an EXEC file, named GLOBAL, that 
contained a single record: 

global maclib cmslib osmacro 
Then, every time you entered the command name: 

global 

the command GLOBAL MACLIB CMSLIB OSMACRO would execute. 

As another example, suppose you had an EXEC file named 'T*, that 
contained the following records: 

&CONTROL OFF 
CP QUERY TIME 

Then, whenever you entered: 

t 
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you would receive the CP time-of-day message, and you could no longer 
use the truncation "T" for the CMS command TYPE. In order to see the 
contents of a CMS file displayed at your terminal you would have to 
enter at least "tY" as a truncation. 



CONTROLLING KEYBOARD-DEPENDENT COMMUNICATIONS 

You are dependent on your terminal for communication with VM/370: when 
your virtual machine is waiting for a read either from the control 
program or from your virtual machine operating system, you can not 
receive messages until you press the Return key to enter a command or a 
null line. If you are in a situation where you must wait for a message 
before continuing your work, for example, if you are waiting for a tape 
device to be attached to your virtual machine, you can use the CP 
command SLEEP to lock your keyboard: 

cp sleep 

You must then press the Attention key to get out of sleep and unlock the 
keyboard so you can enter a command. 

If your virtual machine is in the CP environment when you issue the 
SLEEP command, or if you issue the SLEEP command from the CMS 
environment using the #CP function, your virtual machine is in the CP 
environment after you press the Attention key. If your virtual machine 
is in the CMS environment when you enter the SLEEP command (or if you 
enter CP SLEEP) , your virtual machine is in the CMS environment when you 
press the Attention key once. 

You can control the effect of pressing the Attention key on your 
terminal with the CP TERMINAL command. If you specify: 4 



cp terminal mode cp 

then, whenever you press the Attention key, you are in the CP 
environment. 

If you use the default terminal mode setting, which is VM, and then 

you press the Attention key once, you cause a read to your virtual 

machine; if you press the Attention key twice you cause a CP read, and 
you are in the CP environment. 

The effect of pressing the Attention key is also important when you 
are executing a program. At times, you may wish to enter some CP 
commands while your program executes, but you do not want to interrupt 
the execution of the program. If, before you begin your program you 
issue the command: 

cp set run on 

and then use the Attention key to get to the CP environment while your 
program executes, the program continues executing while you communicate 
with CP. The default setting for the RUN operand of the SET command is 
off; usually, when you press the Attention key (twice) during program 
execution, your program is interrupted. 

SPECIAL CHARACTER SETS: If you are using a programming language or 
entering data that requires you to use characters that are not on your 
keyboard, you can select some characters that you do not use very often 
and establish a translate table with the SET command. For example, if 
your terminal does not have the special characters [ and ] (which have 
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the hexadecimal values AD and BD^ respectively) , you could issue the 
commands: 

set input % ad 
set input $ bd 

Then, when you are entering data lines at your terminal, whenever you 
enter the characters "%" or "$", they are translated and written into 
your file as "[" and " ]" . When you display these lines, the character 
positions occupied by the special characters appear to be blanks, 
because they are not available on your keyboard. If you want these 
special characters to appear on your terminal in symbolic form, you 
should issue the commands: 

set output ad % 
set output bd $ 

so that when you are displaying lines that contain these characters, 
they will appear translated as % and $ on your terminal. If you are 
going to use the input and output functions together, you must set the 
output character first; if you set the input character first, then you 
are unable to set the output function. 

If you are an APL user and have the special APL type font or the APL 
3270 feature and keyboard, you can tell VM/370 to use APL translation 
tables with the command: 

cp terminal apl on 



Commands to Create, Modify, and Move Data Files 
and Programs 

The CMS command language provides you with many different ways of 
manipulating files. A file, in CMS, is any collection of data; it is 
most often a disk file, but it may also be contained on cards or tape, 
or it may be a printed or punched output file. 



COMMANDS THAT CREATE TILES 

YOU create files in CMS by several methods; either specifically or by 
default. The EDIT command invokes the CMS editor to allow you to create 
a file directly at your terminal. You must specify a file identifier 
when you are creating a new file: 

edit mother goose 

In this example, the file has an identifier, or fileid, of MOTHER GOOSE. 
The EDIT subcommand INPUT allows you to begin inserting lines of data or 
source code into this file. When you issue the subcommands FILE or 
SAVE, the lines that you have entered are written into a CMS disk file. 

Files are created, and sometimes named, by default, with the 
following types of commands: 

• Commands that invoke programming language processors or compilers. 
For example, if you issue the command: 

assemble myfile 
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the assembler assembles source statements from an existing CMS file 
named MYFILE ASSEMBLE and produces an output file containing object 
code, as well as a listing. The files that are created are named: 

MYFILE TEXT < 

MYFILE LISTING 

• Commands that load CMS files onto a disk from cards or tapes. These 
commands are HEADCARD, TAPE LOAD, and DISK LOAD. 

• The LISTFILE and LISTIO commands with the EXEC option create files 
named CMS EXEC and $LISTIO EXEC which you can execute as EXEC 
procedures. 

• The TAPPDS and TAPEMAC commands create CMS disk files from OS data 
sets on tape. If the data set is a partitioned data set, the TAPPDS 
command creates individual CMS files from each of the members; the 
TAPEMAC command creates a CMS macro library, called a MACLIB, from an 
OS macro library. 

• The MOVEFILE and FILEDEF commands, used together, can copy OS or DOS 
data sets or files into CMS files; they can also copy files from 
cards or tapes. 

• CMS/DOS commands SSERV, ESERV, RSERV, and PSERV copy DOS files from 
source statement, relocatable, and procedure libraries into CMS 
files. 

• Some CMS commands produce maps, or lists of files, data sets, or 
program entry points. For example, if you issue the command: 

tape scan (disk 

a CMS disk file named TAPE MAP is created that contains a list of the /i 
CMS files that exist on a tape attached to your virtual machine at y 
virtual address 181. 

Some commands create new files from files that already exist on your 
virtual disks. The creation may involve a simple copy operation, or it 
may be a combining of many files of one type into a larger file of the 
same or a different type: 

• The COPYFILE command, in its simplest form, copies a file from one 
virtual disk to another: 

copyfile yourprog assemble b myprog assemble a 

• The MACLIB and TXTLIB commands create libraries from MACRO or COPY 
files, or from TEXT (object) files. 

• The SORT command rearranges (in alphameric sequence) the records in a 
file and creates a new file to contain the result. You have to 
specify the name of the new file: 

sort nonseq recs a seq recs a 

• The GENMOD command creates nonrelocatable modules from object modules 
that you have loaded into your virtual storage area. For example, 
the commands: 



load test 
genmod payroll 

create a file named PAYROLL MODULE, which you can then execute as a 
user-written CMS command. 
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The DOSLKED command creates or adds members to DOSLIBs, which are 
libraries containing link-edited CMS/DOS program phases. 

The UPDATE command creates an updated source file and special update 
files when you use it to apply updates to your source programs. 



COMMANDS THAT MODIFY DISK FILES 

You can use the CMS editor to modify existing files on your virtual 
disks. You issue the EDIT command, giving the file identifier: 

edit old file 

CMS editor subcommands allow you to make minor specific changes or 
global changes, which can affect many lines in a file at one time. 

The MACLIB and TXTLIB commands also allow you to modify CMS macro and 
text libraries. You can add, delete, or replace members in these 
libraries using these commands. 

The COPYFILE command has some options that allow you to change a file 
without creating a new output file. For example, if you enter the 
command: 

copyfile my file a (lowcase 

then all of the uppercase characters in the file MY FILE are translated 
to lowercase. 

You can change the file identifier of a file using the RENAME 
command: 

rename test file a1 good file a1 

The ERASE command deletes files from your virtual disks: 

erase temporary file b1 

For additional examples of CMS file system commands, see "Appendix D: 
Sample Terminal Sessions." 

COMMANDS TO MOVE FILES 

You can use CMS commands to transfer a data file from one device or 
medium to another device of the same or of a different type. The types 
of movement and the commands to use are described briefly here and in 
detail in "Section 7. Using Real Printers, Punches, Readers, and Tapes." 

If you need to transfer files between virtual machines, you can use 
the PUNCH or DISK DUMP commands to punch virtual card image records. 
These are then placed in the virtual card reader of the receiving 
virtual machine. 

Before you use either of these commands, you must indicate the output 
disposition of the files. You do this with the CP SPOOL command: 

cp spool OOd to mickey 
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Then, you can use the PUNCH command to punch virtual card images: 

punch acct records 

The file ACCT RECORDS is spooled to the userid MICKEY'S virtual card 
reader. If the CMS file you are transferring does not have fixed- 
length, 80-character (card image) records, you can use the command: 

disk dump acct records 

The CMS TAPE command allows you to dump CMS files onto tape, or to 
restore previously dumped files: 

tape dump archive file 
tape load archive file 

YM/370 also provides a special utility program, DASD Dump Restore, 
that allows you to dump the entire contents of your virtual disk onto a 
tape and then later restore it to a disk. You might use this program, 
invoked by the DDR command in CMS, to back up your data files before 
using them to test a new program. 



COMMANDS TO PRINT AND PUNCH FILES 

The commands that you use most often to print and punch CMS files are 
the commands PRINT and PUNCH. For example: 

print myprog listing 

prints the contents of the LISTING file on the system printer, and: 

punch myprog assemble i| 

punches the assembler language source statement file onto cards. You 
can also punch members of MACLIBs and TXTLIBs: 

punch cmslib maclib (member fscb 

Some CMS commands have a PRINT option, so that instead of having some 
kinds of output displayed at your terminal or placed in a disk file, you 
can request to have it printed on the real system printer. For example, 
if you want a list of the contents of a macro library to print, you 
could issue the command: 

maclib map mylib (print 

You can see the contents of a file displayed at your terminal by 
using the TYPE command: 

type weeks report 

You can specify, on the TYPE command, that you want to see only some 
specific records in this file: 

type weeks report a 1 20 



i 
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Commands to Develop and Test OS and CMS 
Programs 

Ose CMS to prepare programs: you can create then with the CMS editor, or 
write them onto your CMS disks using any of the methods discussed above. 
You can also assemble or compile source programs directly from cards, 
tapes, or OS data sets. If your source program is in a CMS disk file, 
then during the development process you can use the editor to make 
corrections and updates. 

To compile your programs, use the assembler or any of the language 
processors available at your installation- If your program uses macros 
that are contained in either system or private program libraries, you 
must make these libraries known to CMS by using the GLOBAL command: 

global maclib cmslib asmlib 

In this example, you are using two libraries: the CMS macro library, 
CMSLIB MACLIB, and a private library, named ASMLIB MACLIB. 

The output from the compilers, in relocatable object form, is stored 
on a CMS disk as a file with the filetype of TEXT. To load TEXT files 
into virtual storage to execute them, use the LOAD command: 

load myprog 

The LOAD command performs the linkage editor function in CMS,. If 
MYPROG contains references to external routines, and these routines are 
the names of CMS TEXT files, those TEXT files are automatically included 
in the load. If you receive a message telling you that there is an 
undefined name (which might happen if you have a CSECT name or entry 
point that is not the same as the name of the TEXT file that contains 
it), you can then use the INCLUDE command to load this TEXT file: 

include scanrtn 

Hhen you have loaded the object modules into storage, you can begin 
program execution with the START command: 

start 

If you want to begin execution at a specified entry point, enter: 

start scan1 

where SCANI is the name of a control section, entry point, or procedure. 

If you are testing a program that either reads or writes files or 
data sets using OS macros, you must use the FILEDEF command to supply a 
file definition to correspond to the ddname you specify in your program. 
The command: 

filedef indd reader 

indicates that the input file is to be read from your virtual card 
reader. A disk file might be defined: 

filedef outdd disk out file a1 

The FILEDEF command in CMS performs the same function as a data 
definition (DD) card in OS. 

The commands to load and execute OS programs are discussed in 
"Section 8. Developing OS Programs Under CMS." 
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The RUN command, which is actually an EXEC procedure, combines many 
of these commands for you, so that if you want to compile, load, and 
execute a single source file, or load and execute a TEXT or MODOLE file, 
you can use the RUN command instead of issuing a series of commands. See 
the discussion of the RUN command in VM/STO CMS Command and Macro 
Reference for a list of the OS language processors available. 



Commands to Develop and Test DOS Programs 

I CMS simulates many functions of DOS/VSE in the CMS/DOS environment. 
CMS/DOS is not a separate system, but is part of CMS. When you enter the 
command: 

set dos on 

you are in the CMS/DOS environment. If you want to use the libraries on 
I the DOS/VSE system residence volume, you should access the disk on which 
it resides and specify the mode letter on the SET DOS ON command line: 

access 132 c 
set dos on c 

Using commands that are available only in the CMS/DOS environment, 
you can assign system and programmer logical units with the ASSGN 
command: 

assgn sys200 reader 

If the device is a disk device, you can set up a data definition with 
the DLBL command: 

assgn syslOO b 

dlbl infile b dsn myinput file (syslOO 

You can find out the current logical unit assignments and active file 
definitions with the LISTIO and QUERY DLBL commands, respectively: 

listio a 
query dlbl 

If you are an assembler language programmer, you can assemble a 
source file with the ASSEMBLE command: 

assemble myprog 

A CMS file with a filetype of DOSLIB simulates a DOS core image 

library; you can link-edit TEXT files or relocatable modules from a DCS 

relocatable library and place the link-edited phase in a DOSLIB using 
the DOSLKED command: 

doslked myprog newlib 

Then, use the GLOBAL command to identify the phase library and issue the 
FETCH command to bring the phase into virtual storage: 

global doslib newlib 
fetch myprog 

The START command begins program execution: 

start 
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During program development with CMS, you can use DOS/VS system or 
private libraries. You can use files on these libraries or you can copy 
them into CMS files. The DSERV command displays the directories of 
DOS/VS libraries. The command: 

dserv cd 

produces a copy of the directory for the core image library. To copy 
phases from relocatable libraries into CMS TEXT files, you could use the 
RSERV command: 1 

rserv oldprog 

The SSERV and ESERV commands are available for you to copy files from 
source statement libraries, or copy and de-edit macros from E 
sublibraries. Also, the PSERV command copies procedures from the 
procedure library. 

The CMS/DOS commands are described in detail in "Section 9. 
Developing DOS Programs Under CMS." 



Commands Used in Debugging Programs 

When you execute your programs under CMS, you can debug them as they 
execute, by forcing execution to halt at specific instruction addresses. 
You do this by entering the debug environment before you issue the START 
command. You enter the debug environment with the DEBUG command: 

debug 

To specify that execution be stopped at a particular virtual address, 
you can use the BREAK subcommand to set a breakpoint. For example: 

break 1 20ad0 

Then, when this virtual address is encountered during the execution of 
the program, the debug environment is entered and you can examine 
registers or specific storage locations, or print a dump of your virtual 
storage. Subcommands that do these things might look like the 
following: 

gpr 15 
X 20c12 8 
dump 20000 * 

Instead of using the CMS DEBUG subcommands, you can use the CP ADSTOP 
command to set address stops. For example: 

cp adstop 20ad0 

Then, in the CP environment, you can use CP commands to do the same 
things. For example: 

cp display g 

cp display 20c12.8 

cp dump 20000 

Both sets of commands shown in these examples result in displays of (1) 
the contents of your virtual machine's general purpose registers, (2) a 
display of eight bytes of storage beginning at location X*20C12» and (3) 
a dump of virtual storage from location X» 20000* to the end. 
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You can also use the CMS SVCTRACE command and the CP TRACE commands 
to see a record of interruption activity in your virtual machine. 

The DEBUG subcommands and the CMS and CP debugging facilities are 
described in more detail in "Section 11. How VM/370 Can Help You Debug 
Your Programs." 

Commands to Request Information 

All of the CP and CMS commands discussed in this section have required 
some action on your part: you set your terminal characteristics, 
manipulate disk files, develop, compile, and test programs, and control 
your virtual machine devices and spool files. During a terminal session 
you can change the status of many of your devices and virtual machine 
characteristics, modify the files on your disks and create spool files. 
YM/370 provides many commands to help you find out what is and what is 
not currently defined in your virtual machine. 



COMMANDS TO REQUEST INFORMATION ABOUT TERMINAL CHARACTERISTICS 

You can find out .the status of your terminal characteristics by using 
the CP command QUERY with the TERMINAL or SET operands. If you issue the 
command: 

cp query terminal 

you can see the settings for all of the functions controlled by the CP 

TERMINAL command, including the current line size and line editing L 

symbols. 

Similarly, the command: 

cp query set 

tells you the settings for the functions controlled by the CP SET 
command, such as error message display, and the BSG and WNG flags. 

For most of the functions controlled by the CMS SET command, there 
are corresponding CMS QUERY command operands; to find out a particular 
setting, you must specify the function in the QUERY command. For 
example: 

query input 

lists the current settings in effect for input character translation. 
Other functions that you can query this way are: 

BLIP INPUT REDTYPE 

IMPCP OUTPUT SYNONYM 

IMPEX RDYMSG 






I 
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COMMAMDS TO REQUEST INFORHiTION ABOUT DATA FILES 

Use the LISTFILE command to get information about CHS files. The 
information you can obtain from the LISTFILE command includes: 

• The names of all the files on your A-disk: 

listfile 

• The names of all the files on any other accessed disk: 

listfile * * b 

• The names of all files that have the same filename: 

listfile myprog * 

• The names of all files with the same filetype: 

listfile * assemble 

• The record length and format, blocksize, creation date and disk label 
for a particular file: 

listfile records saved a2 (label 

Use the STATE command to find out whether a certain file exists: 

state sales list c 

If you want to know if the file is on a read/write disk, you can use the 
STATEH command. 

To find out what CMS libraries have been made available, you can use 
the commands: 

query doslib 
query maclib 
query txtlib 
query library 

To find out what members are contained in a particular macro or text 
library use the commands: 

maclib map mylib (term 
txtlib map proglib (term 

The HODHAP command displays a load map of a MODULE file: 

modmap payroll 

To examine load maps created by the LOAD command, use the TYPE 
command: 

type load map a5 

The TYPE command can also be used to display the contents of any CMS 
file. To examine large files, you can use the PRINT command to spool a 
copy to the high-speed printer. 

To compare the contents of two files to see if they are identical, 
use the COMPARE command: 

compare labor stat a1 labor stat b1 
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Any records in these files that do not match are displayed at your 
terminal. 

If you have OS or DOS diskis attached to your virtual machine, you can 
display a list of OS data sets or DOS files by using the LISTDS command; 
for example: 

listds d 

displays a list of the data sets or files on the OS or DOS disk accessed 
as your D-disk. 



COMMANDS TO REQUEST INFORMATION ABOOT YOUR VIRTUAL DISKS 

Use the CP QUERY command to find out: 

• What virtual disks are currently part of your configuration: 

cp query virtual dasd 

• Whether a particular virtual disk address is in use: 

cp query virtual 291 

• What users might be linked to one of your disks: 

cp query links 330 

The CMS QUERY command can tell you about your accessed disks. If you 
enter: 

J 

query disk a '\ 

you can find out the number of files on your A-disk, the amount of space 
that is being used, and its percentage of the total disk space, and the 
read/write status. To get this information for all of your accessed 
disks, issue the command: 

query disk * 

To obtain information about the extents occupied by files on OS and DOS 
disks, enter the command: 

listds * (extent 

If you want to know the current order in which your disks are 
searched for data files or programs, issue the command: 

query search 

You could also use this command to find out what disks you have 
accessed, what filemode letters you have assigned to them, whether they 
are read/write or read-only, and whether they are CMS, OS, or DOS disks. 



COMMANDS TO REQUEST INFORMATION ABOUT YOUR VIRTUAL MACHINE 

If you issue the command: 
cp query virtual 
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you can find out the status of your virtual machine configuration. You 
can also request specific information; for example, the command: 

cp query storage 

gives you the amount of virtual storage you have available. 

To find out the current spooling characteristics of your printer, 
punch, or reader, issue the commands: 

cp query OOe 
cp query OOd 
cp query 00c 

To see information about all three at once, use: 

cp query ur 

For the status of spool files on any of these devices, issue the 
commands: 

cp query printer 
cp query punch 
cp query reader 

Using these commands, you can request the status of particular spool 
files by referring to the spoolid number; for example: 

cp query printer 4187 

You can also request additional information about the files, including 
file identification and creation time: 

cp query reader all 

If you want to know the total number of spool files associated with 
your virtual machine, you can use the command: 

cp query files 

The response to this message is the same as the message you receive if 
you have spool files when you log on. 
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Section 4. The CMS File System 



The file is the essential unit of data in the CMS system. CMS disk 
files are unique to the CMS system and cannot be read or written using 
other operating systems. When you create a file in CMS, you name it 
using a file identifier. The file identifier consists of three fields: 

• Filename (fn) 

• Filetype (ft) 

• Filemode (fm) 

When you use CMS commands and programs to modify, update, or 
reference files, you must identify the file by using these fields. Some 
CMS commands require you to enter only the filename, or the filename and 
filetype; others require you to enter the filemode field as well. This 
section contains information about the things you must consider when you 
give your CMS files their identifiers, notes on the file system commands 
that create and modify CMS files, and additional notes on using CMS 
disks. 

CMS File Formats 

The CMS file management routines write CMS files on disk in fixed 
physical blocks, regardless of whether they have fixed- or 
variable-length records. For most of your CMS applications, you never 
need to specify either a logical record length and record format or 
block size when you create a CMS file. 

When you create a file with the CMS editor, the file has certain 
default characteristics, based on its filetype. The special filetypes 
recognized by the editor, and their applications, are discussed under 
"What are Reserved Filetypes?" 

VSAM files written by CMS are in the same format as VSAM files 
written by OS/VS or DOS/VS and are recognized by those operating 
systems. You cannot, however, use any CMS file system commands to read 
and write VSAM files, because VSAM file formats are unique to the 
virtual storage access method. 

For a minidisk formatted in 800-byte physical blocks, a single CMS 
file can contain up to 12,848,000 bytes of data grouped into as many as 
65,533 logical records, all of which must be on the same minidisk. If 
the file is a source program, the file size limit may be smaller. The 
maximum number of files per real disk in the 800-byte physical block 
format is 3400 for a 3330, 3333, 3340, or 3350 disk, or 3500 for a 2314 
or 2319. 

For a minidisk formatted in 1024-, 2048- , or 4096-byte logical 
blocks, a single CMS file can contain up to about (23i - 132,000) disk 
blocks of data, grouped into as many as 23^-1 logical records, all of 
which must be on the same minidisk. The approximate limits to the 
number of files per disk, expressed in thousands, are: 
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How CMS Files Get Their Names 

When you create a CMS file, you can give it any filename and filetype 
you wish. The rules for forming filenames and filetypes are: 

• The filename and filetype can each be from one to eight characters. 

• The valid characters are A-Z, 0-9, and $, #, S. 

When you enter a command line into the VM/370 system, VM/370 always 
translates your input line into uppercase characters. So, when you 
specify a file identifier, you can enter it in lowercase. 

Remember that, by default, the # and 3 characters are line editing 
symbols in VM/370; when you use them to identify a file, you must 
precede them with the logical escape symbol (") . 

The third field in the file identifier, the filemode, indicates the 
mode letter (A-Z) currently assigned to the virtual disk on which you 
want the file to reside. When you use the CMS editor to create a file, 
and you do not specify this field, the file you create is written on 
your A-disk, and has a filemode letter of A. 

The filemode letter, for any file, can change during a terminal 
session. For example, when you log on, your virtual disk at address 191 
is accessed as your A-disk, so a file on that disk named SPECIAL EVENTS 
has a file identifier of: 

SPECIAL EVENTS A 

If, however, you later access another disk as your A-disk, and access 
your 191 as your B-disk, then this file has a file identifier of: 

SPECIAL EVENTS B 



DUPLICATING FILENAMES AND FILETYPES 

You can give the same filename to as many files on a given disk as you 
want, as long as you assign them different filetypes. Or you can create 
many files with the same filetype but different filenames. 

For the most part, filenames that you choose for your files have no 
special significance to CMS. If, however, you choose a name that is the 
same as the name of a CMS command, and the file that you assign this 
name to is an executable module or EXEC procedure, then you may 
encounter difficulty if you try to execute the CMS command whose name 
you duplicated. 
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For an explanation of how CMS identifies a command name, see "CMS 
Command Search Order" later in this section. 

Many CMS commands allow you to specify one or more of the fields in a 
file identifier as an asterisk (*) or equal sign (=) , which identify 
files with similar fileids. 



Usina Asterisks (*) in Fileids 

Some CMS commands that manipulate disk files allow you to enter the 
filename and/or f iletype fields as an asterisk (*) , indicating that all 
files of the specified filename/f iletype are to be modified. These 
commands are: 

COPYFILE RENAME 
ERASE TAPE DUMP 

For example, if you specify: 

erase * test a 

all files with a f iletype of TEST on your A-disk are erased. 
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The LISTFILE command allows you to request similar lists. If you 
specify an asterisk for a filename or filetype, all of the files of that 
filename or filetype are listed. There is an additional feature that you 
can use with the LISTFILE command, to obtain a list of all the files 
that have a filename or filetype that begin with the same character 
string. For example: 

listfile t* assemble 

produces a list of all files on your A-disk whose filenames begin with 
the letter T. The command: 

listfile tr* a* 

produces a list of all files on your A-disk whose filenames begin with 
the letters TR and whose filetypes begin with the letter A. 



Equal Signs in Outgut Fileids 

The COPYFILE, RENAME, and SORT commands allow you to enter output file 
identifiers as equal signs (=) , to indicate that it is the same as the 
corresponding input file identifier. For example: 

copyfile myprog assemble b = = a 

copies the file MYPROG ASSEMBLE from your B-disk to your A-disk, and 
uses the same filename and filetype as specified in the input fileid for 
those positions in the output fileid. 

Similarly, if you enter the command: 

rename temp * b perm = = 

all files with a filename of TEMP are renamed to have filenames of PERM; 
the existing filetypes of the files remain unchanged. 



What Are Reserved Filetypes? 

For the purposes of most CMS commands, the filetype field is used merely 
as an identifier. Some filetypes, though, have special uses in CMS; 
these are known as "reserved filetypes." 

Nothing prevents you from assigning any of the reserved filetypes to 
files that are not being used for the specific CMS function normally 
associated with that filetype. 

Some reserved filetypes also have special significance to the CMS 
editor. When you use the EDIT command to create a file with a reserved 
filetype, the editor assumes various default characteristics for the 
file, such as record length and format, tab settings, translation to 
uppercase, truncation column, and so on. 
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FILETYPES FOR CMS COMMANDS 

Reserved filetypes sometimes indicate how the file is used in the CMS 
system: the filet ype ASSEMBLE, for example, indicates that the file is 
to be used as input to the assembler; the filetype TEXT indicates that 
the file is in relocatable object form, and so on. Many CMS commands 
assume input files of particular filetypes, and require you to enter 
only the filename on the command line. For example, if you enter: 

synonym test 

CMS searches for a file with a filetype of SYNONYM and a filename of 
TEST. A file named TEST that has any other filetype is ignored. 

Some CMS commands create files of particular filetypes, using the 
filename you enter on the command line. The language processors do this 
as well; if you are recompiling a source file, but wish to save previous 
output files, you should rename them before executing the command. 

Figure 2 lists the filetypes used by CMS commands and describes how 
they are used. Figure 3 lists the filetypes used by CMS/DOS commands. 

In addition to these CMS filetypes, there are special filetypes 
reserved for use by the language processors, which are IBM program 
products. These filetypes, and the commands that use them, are: 

Filetypes Commands 

COBOL, SYMDMP, TESTCOB COBOL, FCOBOL, TESTCOB 

FORTRAN, FREEFORT, FORTRAN, FORTGI, FORTHX 

FTnnOOl, TESTFORT GOFORT, TESTFORT 

PLI, PLIOPT DOSPLI, PLIC, PLICR, PLIOPT 

VSBASIC, VSBDATA VSBASIC 

For details on how to use these filetypes, consult the appropriate 
program product documentation. 
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Filetype 



AMSERV 



ASM3705 



ASSEMBLE 



AUXXXXX 



CNTRL 



COPY 



DIRECT 



EXEC 



HELPCMS 

HELPCP 

HELPDEBD 

HELPEDIT 

HELPMENU 

HELPMSG 

LISTING 



LKEDIT 



LOADLIB 



MACLIB 



MACRO 



MAP 



Command 



AMSERV 



ASM3705 
GEN 3705 

ASSEMBLE 



UPDATE 



UPDATE 



MACLIB 



DIRECT 



EXEC 

GEN3705 

LISTFILE 

HELP 



AMSERV 

ASSEMBLE 

ASM3705 

LKED 



LKED 



GLOBAL 
MACLIB 



MACLIB 



INCLUDE 

LOAD 

MACLIB 

TAPE 

TXTLIB 



Comments 



Contains VSAM access method services control 
statements to be executed with the AMSERV 
command . 

Used by system programmers to generate the 
3704/3705 control program. 

Contains source statements for assembler 
language programs. 

Points to files that contain UPDATE control 
statements for multiple updates. 

Lists files that either contain UPDATE control 
statements or point to additional files. 

Can contain COPY control statements and macros 
or copy files to be added to MACLIBs. 

Contains entries for the VM/370 user directory 
file. The system operator controls this file. 

Can contain sequences of CMS or user— written 
commands, with execution control statements- 



Contains descriptive information for CP and 
CMS commands, messages, and menu lists. 



Listings are produced by the assembler and 
the language processors as well as the AMSERV 
command. 

Contains the listing created during the 
generation of the 3704/3705 control program- 
Is a library of 3704/3705 control program 
load modules created during 3704/37 05 control 
program generation. 

Library members contain macro definitions or 
copy files; the MACLIB command creates the 
library, and lists, adds, deletes, or replaces 
members. The GLOBAL command identifies which 
macro libraries should be searched during an 
assembly or compilation. 

Contains macro definitions to be added to a 
CMS macro library (MACLIB) - 

Maps created by the LOAD and INCLUDE commands 
indicate entry point locations; the MACLIB, 
TXTLIB, and TAPE commands produce MAP files- 
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r - 

1 Piletype 


1 Command 


._., . „... _ _ _ ,. ,. .^ 

1 Comments i 


1 MODULE 


1 GENHOD 


MODULE files created by the GENMOD command arej 




1 LOADMOD 


nonrelocatable executable programs. | 




1 MODMAP 


The LOADMOD commands loads a MODULE file for | 
execution; the MODMAP command displays a map I 
of entry point locations. 1 


1 SYNONYM 


SYNONYM 


Contains a table of synonyms for CMS commands I 
and user-written EXEC and MODULE files. I 


1 SCRIPT* 


SCRIPT 


SCRIPT text processor input includes data and | 
SCRIPT control words. I 


1 TEXT 


ASSEMBLE 


TEXT files contain relocatable object code | 




INCLUDE 


created by the assembler and compilers. The 1 




LOAD 


LOAD and INCLUDE commands load them into | 




TXTLIB 


storage for execution. The TXTLIB command | 
manipulates libraries of TEXT files. 1 


1 TXTLIB 


GLOBAL 


Library members contain relocatable object I 




TXTLIB 


code. The TXTLIB command creates the library, | 
and lists or deletes existing members. The | 
GLOBAL command identifies TXTLIBs to search. I 


1 UPDATE 


UPDATE 


Contains UPDATE control statements for single I 
updates applied to source programs. I 


1 UPDLOG 


UPDATE 


Contains a record of additions, deletions, or | 
changes made with the UPDATE command. | 


1 UPDTXXXX 


UPDATE 


Contains UPDATE control statements for | 
multilevel updates. | 


1 ZAP 


ZAP 


Contains control records for the ZAP command, | 
which is used by system support personnel. | 


|»SCRIPT is 


an IBM Inste 


illed User Program (lUP) . I 
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OUTPUT FILES: TEXT AND LISTING 



Output files from the assembler and the language processors are 
logically related to the source programs by their filenames. Some of 
these files are permanent and some are temporary. For example, if you 
issue the command: 

assemble myfile 

CMS locates a file named MYFILE with a filetype of ASSEMBLE and the 
system assembler assembles it. If the file is on your A-disk, then when 
the assembler completes execution, the permanent files you have are: 

MYFILE ASSEMBLE Al 
MYFILE TEXT Al 
MYFILE LISTING Al 
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Filetype | Command | Comments 



COPY I MACLIB I When the SSERV command copies books or macros 

SSERV I from DOS source statement libraries, the output 
is written to CMS COPY files, which can be added 
to CMS macro libraries with the MACLIB command. 

DOSLIB I DOSLIB | DOS core image phases are placed in a DOSLIB by 

DOSLNK I linkage editor, invoked with the DOSLNK command. 

FETCH I The GLOBAL command identifies DOSLIBs to be 

GLOBAL I searched when the FETCH command is executed. 

DOSLNK I DOSLKED | Contains linkage editor control statements for 

input to the CMS/DOS linkage editor. 

ESERV I ESERV | Contains input control statements for the ESERV 

utility program. 

EXEC I LISTIO I The LISTIO command with the EXEC option creates 

the $LISTIO EXEC that lists system and 
programmer logical unit assignments. 

LISTING I ASSEMBLE I Listings contain processor output from the ESERV 
ESERV I command, and compiler output from the assembler 
and language processors. 

MACRO I ESERV | Contains SYSPCH output from the ESERV program, 
MACLIB I suitable for addition to a CMS MACLIB file. 

MAP I DOSLIB I The DSERV command creates listings of the 

DOSLKED I directories of DOS libraries. The DOSLIB command 
DSERV I with the MAP option produces a list of DOSLIB 

members. The linkage editor map from the DOSLKED 
command is written into a MAP file. 

PROC I PSERV I The PSERV command copies procedures from DOS 

procedure libraries into CMS PROC files. 

TEXT I ASSEMBLE I Object decks created by the assembler or 

I DOSLKED I compilers are written into TEXT files. The RSERV 
RSERV I command creates TEXT files from modules in DOS 
relocatable libraries. TEXT files can also be 
used as input to the linkage editor. 
I 1 

Figure 3. Filetypes Used in CMS/DOS 

where the TEXT file contains the object code resulting from the 
assembly, and the LISTING file contains the program listing generated by 
the assembly. If any TEXT or LISTING file with the same name previously 
existed, it is erased. The source input file, MYFILE ASSEMBLE A1, is 
neither erased nor changed. 

The characteristics of the TEXT and LISTING files produced by the 
assembler are the same as those created by other processors and programs 
in CMS. 

Because these files are CMS files, you can use the CMS editor to 
examine or modify their contents. If you want a printed copy of a 
LISTING file, you can use the PRINT command to print it. If you want to 
examine a TEXT file, you can use the TYPE or PRINT command specifying 
the HEX option. 
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Note that if a TEXT file contains control changes for the terminal, 
the edit lines may not be displayed in their true form. Therefore, it 
is suggested you do not use the editor for TEXT files, because the 
results are unpredictable. Instead, use the TYPE and/or PRINT commands 
with the HEX option to display TEXT decks. Put TEXT decks into a TXTLIB 
and ZAP the TXTLIB to modify the TEXT deck. 



FILETYPES FOR TEMPORARY FILES 



The filetypes of files created by the assembler and language processors 
for use as temporary workfiles are: 



SYSUT1 
SYSUT2 
SYS0T3 
SYSUT4 



SYS001 
SYS002 
SYS003 



SYSOOa 
SYS 005 
SYS006 



I CMS handles all SYSUTx and SYSOOx files as temporary files. 

The CMS AMSERV command, executing VSAM utility functions, 
workfiles that have filetypes of LDTFDH and LDTFDI2. 



uses two 



Disk space is allocated for temporary files on an as-needed basis. 
They are erased when processing is complete. If a program you are 
executing is terminated before completion, these workfiles may remain on 
your disk. You can erase them. 



CMS0T1 Files 



The CMSUT1 filetype is used by CMS commands that create files on your 
CMS disks. The CMSOTI file is used as a workfile and is erased when the 
file is created. Hhen a command fails to complete execution properly, 
the CMSUTI file may not be erased. The commands, and the filenames they 
assign to files they create, are listed below. 

Command Filename 

COPYFILE COPYFILE 

DISK LOAD DISK 

EDIT EDIT 

INCLUDE DMSLDR 

LOAD DMSLDR 

MACLIB DM3LBM 

READCARD READCARD 

TAPE LOAD TAPE 

UPDATE fn (the filename of the UPDATE file) 



FILETYPES FOR DOCUMENTATION 



There are two CMS reserved filetypes that accept uppercase and lowercase 
input data. These are MEMO and SCRIPT. You can use MEMO files to 
document program notes or to write reports. The SCRIPT filetype is used 
by the SCRIPT command, which invokes a text processor that is an IBM 
Installed User Program (lUP) . 



( 
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Filemode Letters and Numbers 

The filemode field of a CMS file identifier has two characters: the 
filemode letter and the filemode number. The filemode letter is 
established by the ACCESS command and specifies the virtual disk on 
which a file resides: A through Z. The filemode number is a number from 
to 5, which you can assign to the file when you create it or rename 
it; if you do not specify it, the value defaults to 1. How you access 
your disks and what filemode letters you give them with the ACCESS 
command depends on how you want to use the files that are on them. 

For most of the reading and writing you do of files, you use your 
A-disk, which is also known as your primary disk. This is a read/write 
disk. You may access other disks in your configuration, or access 
linked-to disks, in read-only or read/write status, depending on whether 
you have a read-only or read/write link. 

When you load CMS (with the IPL command) , your virtual disk at 
address 191 is accessed for you as your A-disk. Your virtual disk at 
address 190 (the system disk) is accessed as your S-disk; and the disk 
at 19E is accessed as an extension of your S-disk, with a mode letter of 
Y. In addition, if you have a disk defined at address 192, it is 
accessed for you as your D-disk. If the 192 disk has not been 
formatted, CMS will do it automatically and label the minidisk 'SCRTCH*. 

If ACCESS is the first command issued after an IPL of the CHS system, 
only the A-disk is not automatically defined. Another ACCESS command 
must be issued to define the A-disk. 

The actual letters you assign to any other disks (and you may 
reassign the letters A, D, and Y) , is arbitrary; but it does determine 
the CMS search order, which is the order in which CMS searches your 
disks when it is looking for a file. The order of search (when all disks 
are being searched) is alphabetical: A through Z. If you have duplicate 
file identifiers on different disks, you should check your disk search 
order before issuing commands against that filename to be sure that you 
will get the file you want. You can find out the current search order 
for your virtual disks by issuing the command: 

guery search 

You can also access disks as logical extensions of other disks, for 
example: 

access 235 b/a 

The "/A" indicates that the B-disk is to be a read-only extension of the 
A-disk, and the A-disk is considered the "parent" of the B-disk. A disk 
may have many extensions, but only one level of extension is allowed. 



il5* Extensions Are Osed 

If you have a disk accessed as an extension of another disk, the 
extension disk is automatically read-only, and you cannot write on it. 
You might access a disk as its own extension, therefore, to protect the 
files on it, so that you do not accidentally write on it. For example: 

access 235 b/b 
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Another use of extensions is to extend the CHS search order. If you 
issue a comaand requesting to read a file, for example: 

type alpha plan 

CMS searches your A-disk for the file named ALPHA PLAN and if it does 
not find it, searches any extensions that your A-disk may have. If you 
have a file named ALPHA PLAN on your B-disk but have not accessed it as 
an extension of your A-disk, CMS will not find the file, and you will 
have to reenter the command: 

type alpha plan b 

Additionally, if you issue a CMS command that reads and writes a 
file, and the file to be read is on an extension of a read/write disk, 
the output file is written to the parent read/write disk. The EDIT 
command is a good example of this type of command. If you have a file 
named FINAL LIST on a B-disk extension of a read/write A-disk, and if 
you invoke the editor to modify the file with the command: 

edit final list 

after you have made modifications to the file, the changed file is 
written onto your A-disk, The file on the B-disk remains unchanged. 

Accessing and Releasing Read-Onl^ Extensions 

When you access a disk as a read-only extension, it remains an extension 
of the parent disk as long as both disks are still accessed. If either 
disk is released, the relationship of parent disk/extension is 
terminated. 

If the parent disk is released, the extension remains accessed and 
you may still read files on it. If you access another disk at the mode 
letter of the original parent disk, the parent/extension relationship 
remains in effect. 

If you release a read-only extension and access another disk with the 
same mode letter, it is not an extension of the original parent disk 
unless you access it as such. For example, if you enter: 

access 1 98 c/a 
release c 
access 199 c 

the C-disk at virtual address 199 is not an extension of your A-disk. 

WHEN TO SPECIFY FILEMODE LETTERS: READING FILES 

When you request CMS to access a file, you have to identify it so that 
CMS can locate it for you- The commands that expect files of particular 
filetypes (reserved filetypes) allow you to enter only the filename of 
the file when you issue the command. When you execute any of these 
commands or execute a MODULE or EXEC file, CMS searches all of your 
accessed disks (using the standard search order) to locate the file. 
The CMS commands that perform this type of search are: 



AMSERV 


GLOBAL 


MODMAP 


ASSEMBLE 


LOAD 


RUN 


DOSLIB 


LOADMOD 


TXTLIB 


EXEC 


MACLIB 
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Some CMS commands require you to enter the filename and filetype to 
identify a file. You may specify the filemode letter; if you do not 
specify the filemode, CMS searches only your A-disk and its extensions 
when it looks for the file. If you do specify a filemode letter, the 
disk you specify and its extensions are searched for the file. The 
commands you use this way are: 



EDIT 


PUNCH 


TAPE DUMP 


ERASE 


STATE 


TYPE 


FILEDEF 


SYNONYM 


UPDATE 



There are two CMS commands that do not search extensions of disks 
when looking for files. They are: 

DISK DUMP 
LISTFILE 

You must explicitly enter the filemode if you want to use these commands 
to list or dump files that are on extensions. 



Ii§ifi3 Asterisks and Egual Signs 

For some CMS commands, if you specify the filemode of a file as an 

asterisk, it indicates that you either do not know or do not care what 

disk the file is on and you want CMS to locate it for you. For example, 
if you enter: 

listfile myfile test * 

the LISTFILE command responds by listing all files on your accessed 

disks named MYFILE TEST. When you specify an asterisk for the filemode 

of the COPYFILE, ERASE, or RENAME commands, CMS locates all copies of 
the specified file. For example: 

rename temp sort * good sort = 

renames all files named TEMP SORT to GOOD SORT on all of your accessed 
read/write disks. An equal sign (=) is valid in output fileids for the 
I RENAME and COPYFILE commands. 

For some Commands, when you specify an asterisk for the filemode of a 
file, CMS stops searching as soon as it finds the first copy of the 
file. For example: 

type myfile assemble * 

If there are files named MYFILE ASSEMBLE on your A-disk and C-disk, then 
only the copy on your A-disk is displayed. The commands that perform 
this type of search are: 

STATE 
SYNONYM 
TAPE DUMP 
TYPE 

For the COMPARE, COPYFILE, RENAME, and SORT commands, you must always 
specify a filemode letter, even if it is specified as an asterisk. 



COMPARE 


PRINT 


DISK DUMP 


PUNCH 


EDIT 


RUN 


FILEDEF 


SORT 
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WHEN TO SPECIFY FILEMODE LETTERS: WRITING FILES 

When you issue a CMS command that writes a file onto one of your virtual 
disks, and you specify the output filemode, CMS writes the file onto 
that disk. The commands that require you to specify the output filemode 
are: 

COPYFILE 

RENAME 

SORT 

The commands that allow you to specify the output filemode, but do 
not require it, are: 

FILEDEF TAPE LOAD 
GENMOD TAPPDS 

READCARD UPDATE 

When you do not specify the filemode on these commands, CMS writes the 
output files onto your A-disk. 

Some CMS commands that create files always write them onto your 
A-disk. The LOAD and INCLUDE commands write a file named LOAD MAP A5. 
The LISTFILE command creates a file named CMS EXEC, on your A-disk. The 
CMS/DOS commands DSERV, ESERV, SSERV, PSERV, and RSERV also write files 
onto your A-disk. 

Other commands that do not allow you to specify the filemode, write 
output files either: 

• To the disk from which the input file was read, or 

• To your A-disk, if the file was read from a read-only disk 

These commands are: 

AMSER7 
MACLIB 
TXTLIB 
UPDATE 

The SORT command also functions this way if you specify the output 
filemode as an asterisk (*) . 

In addition, many of the language processors, when creating work 
files and permanent files, write onto the first read/write disk in your 
search order, if they cannot write on the source file's disk or its 
parent. 



HOW FILEMODE NUMBERS ARE USED 

Whenever you specify a filemode letter to reference a file, you can also 
specify a filemode number. Since a filemode number for most of your 
files is 1, you do not need to specify it. The filemode numbers 0, 2, 
3, 4, and 5 are discussed below. Filemode numbers 6 through 9 are 
reserved for IBM use. 

Filemode 0: A filemode number of assigned to a file makes that file 
private. No other user may access it unless they have read/write access 
to your disk. If someone links to your disk in read-only mode and 
requests a list of all the files on your disk, the files with a filemode 
of are not listed. 
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Fileaode 2: Filemode 2 is essentially the sane, for the purposes of 
reading and writing files, as filemode 1. Usually a fileaode of 2 is 
assigned to files that are shared by users who link to a coamon disk, 
like the system disk. Since you can access a disk and specify which 
files on that disk you want to access, files with a filemode of 2 
provide a convenient subset of all files on a disk. For exapiple, if you 
issue the command: 

access 489 e/a * * e2 

you can only read files with a filemode of 2 on the disk at virtual 
address 489. 

Filemode 3: Files with a filemode of 3 are erased after they are read. 
If you create a file with a filemode of 3 and then request that it be 
printed, the file is printed, and then erased. You can use this filemode 
if you write a program or EXEC procedure that creates files that you do 
not want to maintain copies of on your virtual disks. You can create the 
file, print it, and not have to worry about erasing it later. 

The language processors and some CMS commands create work files and 
give these work files a filemode of 3. 

Note: A filemode of 3 should not be used with EXECs. Depending on what 
commands are issued within it, an EXEC with a filemode of 3 may be 
erased before it completes execution- 

Filemode 4: Files with a filemode of 4 are in OS simulated data set 
format. These files are created by OS macros in programs running in 
CMS. You specify that a file created by a program is to have OS 
simulated data set format by specifying a filemode of 4 when you issue 
the FILEDEF command for the output file. If you do not specify a 
filemode of 4, the output file is created in CMS format. 

You can find more details about OS simulated data sets in "Section 8. 
Developing OS Programs Under CMS." 

Note: There are no filemode numbers reserved for DOS or VSAM data sets, 
since CMS does not simulate these file organizations. 

Filemode 5: This filemode number is the same, for purposes of reading 
and writing, as filemode 1. You can assign a filemode of 5 to files that 
you want to maintain as logical groups, so that you can manipulate them 
in groups- For example, you can reserve the filemode of 5 for all files 
that you are retaining for a certain period of time; then, when you want 
to erase them, you could issue the command: 

erase * * a5 



1^®S l2 llii§£ lil®12^§ Numbers 

You can assign filemode numbers when you use the following commands: 

COPYFILE: You can assign a filemode number when you create a new file 
with the COPYFILE command. To change only the filemode number of an 
existing file, you must use the REPLACE option. For example: 

copy file test module a1 = = a2 (replace 

changes the filemode number of the file TEST MODULE A from 1 to 2- 
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EDIT : You can assign a filemode number vhen you create a file with the 
CMS editor. To change the filemode number of an existing file, use the 
RENAME or COPYFILE commands, or use the FMODE subcommand when you are in 
the edit environment. 

UliMlif FILEDEF: When you assign file definitions to disk files for 
programs or CMS command functions, you can specify a filemode number. 

GENMOD: You can specify a filemode number on the GENMCD command line. 
To change the filemode number of an existing MODULE file, use the EENAHE 
or COPYFILE commands. 

READCARD: You can assign a filemode number when you specify a file 
identifier on the READCARD command line or on a READ control card. 

RENAME; When you specify the fileids on the RENAME command, you can 
specify the filemode numbers for the input and/or output files. 

SORT; You can specify filemode numbers for the input and/or output 
fileids on the SORT command line. 



Managing Your CMS Disks 

The number of files you can write on a CMS disk depends on both the size 
of the disk and the size of the files that it contains- You can find 
out how much space is being used on a disk by using the QUERY DISK 
command. For example, to see how much space is on your A-disk, you would 
enter: 

query disk a 

The response may be something like this: 

I LABEL cuu M STAT CYL TYPE BLKSIZE FILES BLKS USED- (%) ELKS LEFT BLK TOTAL 
I ^MYDISK 191 A R/W 5 3330 102^ 171 1221-92 107 1328 

When a disk is becoming full, you should erase whatever files you no 
longer need- Or dump to tape files that you need to keep but do not need 
to keep active on disk- 
When you are executing a command or program that writes a file to 
disk, and the disk becomes full in the process, you receive an error 
message, and you have to try to clear some space on the disk before you 
can attempt to execute the command or program again. To avoid the 
delays that such situations cause, you should try to maintain an 
awareness of the usage of your disks. If you cannot erase any more 
files from your disks, you should contact installation support personnel 
about obtaining additional read/write CMS disk space. 



CMS File Directories 

Each CMS disk has a master file directory that contains entries for each 
of the CMS files on the disk. When you access a disk, information from 
the master file directory is brought into virtual storage and written 
into a user file directory- The user file directory has an entry for 
each file that you may access- If you have accessed a disk specifying 
only particular files, then the user file directory contains entries 
only for those files. J 
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If you have read/write access to a disk, then each tiie you write the 
file onto disk the user file directory and master file directory are 
updated to reflect the current status of the disk. If you have read-only 
access to a disk, then you cannot update the master file directory or 
user file directory. If you access a read-only disk while another user 
is writing files onto it, you may need to periodically reissue the 
ACCESS command for the disk, to obtain a fresh copy of the master file 
directory. 

Note: YOU should never attempt to write on a disk at the same time as 
another user. 

The user file directory remains in virtual storage until you issue 
the RELEASE command specifying the mode letter or virtual address of the 
disk. If you detach a virtual disk (with the CP DETACH command) without 
releasing it, CHS does not know that the disk is no longer part of your 
virtual machine. When you attempt to read or write a file on the disk 
CHS assumes that the disk is still active (because the user file 
directory is still in storage) and encounters an error when it tries to 
read or write the file. 

A similar situation occurs if you detach a disk and then add a new 

disk to your virtual machine using the same virtual address as the disk 

you detached. For example, if you enter the following sequence of 
commands: 

cp link user1 191 195 rr rpass^ 

access 195 d 

cp detach 195 

cp link user2 193 195 rr rpass2i 

listfile * * d 

the LISTFILE command produces a list of the files on DSERl»s 191 disk; 
if you attempt to read one of these files, you receive an error message. 
Tou must issue the ACCESS command to obtain a copy of the master file 
directory for 0SER2»s 193 disk. 

The entries in the master file directory are sorted alphamerically by 
filename and filetype, to facilitate the CMS search for particular 
files. When you are updating disk files, the entries in the user file 
directory and master file directory tend to become unsorted as files are 
created, updated, and erased. When you use the RELEASE command to 
release a read/write disk, the entries are sorted and the master file 
directory is rewritten. If you or any other user subsequently access 
the disk, the file search may be more efficient. 

CMS Command Search Order 

When you enter a command line in the CMS environment, CMS has to locate 
the command to execute. If you have EXEC or MODDLE files on any of your 
accessed disks, CHS treats them as commands; also, they are known as 
user-written commands. 

As soon as the command name is found, the search stops and the 
command is executed. The search order is: 

1. EXEC file on any currently accessed disk. CHS uses the standard 
search order (A through Z.) 



^Note that the password cannot be entered on the command line if the 
password suppression facility was specified at sysgen. 
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2. Valid abbreviation or truncation for an EXEC file on any currently 
accessed disk, according to current SYNONYM file definitions in 
effect. 

3. A command that has already been loaded into the transient area. 
The transient area commands are: 

ACCESS I HELP RELEASE 

ASSGN LISTFILE RENAME 

COMPARE MODMAP SET 

DISK OPTION SVCTRACE 

DLBL PRINT SYNONYM 

FILEDEF PUNCH TAPE 

GENDIRT QUERY TYPE 

GLOBAL READCARD 

4. A nucleus-resident command. The nucleus-resident CMS commands are: 

CP GENMOD START 

DEBUG INCLUDE STATE 

ERASE LOAD STATEW 

FETCH LOADMOD 

5. Command module on any currently accessed disk. (All the remaining 
CMS commands are disk resident and execute in the user area.) 

6. Valid abbreviation or truncation for nucleus-resident or transient 
area command module. 

7. Valid abbreviation or truncation for disk-resident command. 

For example, if you create a command module that has the same name as 
a CMS nucleus-resident command, your command module cannot be executed, 
since CMS locates the nucleus-resident command first, and executes it. 
When a user-written command has the same name as a CMS command module 
abbre'viation, certain error messages may indicate the CMS command name, 
rather than the program name. 

Figure 4 shows more details of the command search order. 
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Figure U. How CMS Searches for the Command to Execute 
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In CMS usage, the term edit is used in a variety of ways, all of which 
refer, ultimately, to the functions of the CMS editor, which is invoked 
when you issue the EDIT command. 

To edit a file means to make changes, additions, or deletions to a 
CMS file that is on a disk, and to make these changes interactively: you 
instruct the editor to make a change, the editor does it, and then you 
reguest another change. 

you can edit a file that does not exist; when you do so, you create 
the file online, and can modify it as you enter it. 

To file a file means to write a file you are editing back onto a 
disk, incorporating any changes you made during the editing session. 
When you issue the FILE subcommand to write a file, you are no longer in 
the environment of the CMS editor, but are returned to the CMS 
environment. You can, however, write a file to disk and then continue 
editing it, by using the SAVE subcommand. 

An editing session is the period of time during which a file is in 
your virtual storage area, from the moment you issue the EDIT command 
and the editor responds EDIT: until you issue the FILE or QUIT 
subcommands to return to the CMS command environment. 



The EDIT Command 

When you issue the EDIT command you must specify the filename and 
filetype of the file you want to edit. If you issue: 

edit test file 

CMS searches your A-disk and its extensions for a file with the 
identification TEST FILE. If the file is not found, CMS assumes that you 
want to create the file and issues the message: 

NEW FILE: 
EDIT: 

to inform you that the file does not already exist. 

If the file exists on a disk other than your A-disk and its 
extensions, or if you want to create a file to write on a read/write 
disk other than your A-disk, you must specify the filemode of the file: 

edit test file b 

In this example, your B-disk and its extensions are searched for the 
file TEST FILE. 

After you issue the EDIT command, you are in edit mode, or the 
environment of the CMS editor. If you have specified the filename and 
filetype of a file that already exists, you can now use EDIT subcommands 
to make changes or corrections to lines in that file. If you want to 
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add records to the file, as you would if you are creating a new file, 
issue the EDIT subcommand: 

input 

to enter input mode. Every line that you enter is considered a data line 
to be written into the disk file. For most filetypes, the editor 
translates all of your input data to uppercase characters, regardless of 
how you enter it. For example, if you create a file and enter input 
mode as follows: 

edit myfile test 

NEff FILE: 

EDIT: 

input 

INPDT: 

This is a file I am 

learning to create with the CMS editor. 

the lines are written into the file as: 

THIS IS A FILE I AM 

LEARNING TO CREATE WITH THE CMS EDITOR. 

You can use the VM/370 logical line editing symbols to modify data 
lines as you enter them. 

To return to edit mode to modify a file or to terminate the edit 
session, you must press the Return key on a null line. If you have just 
entered a data line, for example, and your terminal's typing element or 
cursor is positioned at the last character you entered, you must press 
the Return key once to enter the data line, and a second time to enter a 
null line. 

You may also use the logical line end symbol to enter a null line; 
for example: 

last line of input* 
# 

Both of these lines cause you to return to edit mode from input mode. 

If you do not enter a null line, but enter an EDIT subcommand or CHS 
command, the command line is written into your file as input- The only 
exception to this is a line that begins with the characters #CP. These 
characters indicate that the command is to be passed immediately to CP 
for processing. 



WRITING A FILE ONTO DISK 

A file you create and the modifications that you make to it during an 
edit session are not automatically written to a disk file. To save the 
results, you can do the following: 

• Periodically issue the subcommand: 

save 

to write onto disk the contents of the file as it exists when you 
issue the subcommand. Periodically issuing this EDIT subcommand 
protects your data against a system failure; you can be sure that 
changes you make are not lost. 
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• At the beginning of the edit session, issue the AOTOSAVE subcommand, 
with a number: 

autosave 10 

Then, for every tenth change or addition to the file, the editor 
issues an automatic save request, which writes the file onto disk. 

• At the end of the edit session, issue the subcommand: 

file 

This subcommand terminates the edit session, writes the file onto 
disk, replacing a previous file by that name (if one existed) , and 
returns you to the CMS environment. You can return to the edit 
environment by issuing the EDIT command, specifying a different file 
or the same file. 

The editor decides which disk to write the file onto according to the 
following hierarchy: j 

• If you specify a filemode on the FILE or SAVE subcommand line, the 
file is written onto the specified disk. 

• If the current filemode of the file is the mode of a read/write disk, 
the file is written onto that disk. (If you have not specified a 
filemode letter, it defaults to your A-disk.) 

• If the filemode is the mode of a read-only extension of a read/write 
disk, the file is written onto the read/write parent disk. 

• If the filemode is the mode of a read-only disk that is not an 
extension of a read/write disk, the editor cannot write the file and 
issues an error message. 

See "Changing File Identifiers" for information on how you can tell 
the editor what disk to use when writing a file. 

If you are editing a file and decide, after making several changes, 
that you do not wish to save the changes, you can use the subcommand: 

quit 

Ho changes that you made since you last used the SAVE subcommand (or the 
editor last issued an automatic save for you) are retained. If you have 
just begun an edit session, and have made no changes at all to a file, 
and for some reason you do not want to edit it at all (for example, you 
misspelled the name, or want to change a CMS setting before editing the 
file) , you can use the QUIT subcommand instead of the FILE subcommand to 
terminate the edit session and return to CMS. 

A file must have at least one line of data in order to be written. 

EDIT SUBCOMMANDS 

While you are in the edit environment, you can issue any EDIT subcommand 
or macro. An edit macro is an EXEC file that contains a sequence of EDIT 
subcommands that execute as a unit. You can create your own EDIT 
subcommands with the CMS EXEC facility. EDIT subcommands provide a 
variety of functions. You can: 

• Position the current line pointer at a particular line, or record, in 
a file. 
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• Control which columns of a file are displayed or searched during an 
editing session. 

• Modify data lines. 

• Describe the characteristics that a file and its individual records 
will have. 

• Automatically write and update sequence numbers for fixed-length 
records. 

• Edit files by line number. 

• Control the editing session. 



Entering EDIT Subcommands 

Like CMS commands^ EDIT subcommands have a subcommand name and some have 
operands. In most cases, a subcommand name (or its truncation) can be 
separated from its operands by one or more blanks, or no blanks. For 
example, the subcommand lines: 

type 5 
ty 5 
t5 

are equivalent. 

Several subcommands also use delimiters, which enclose a character 
string that you want the editor to operate on. For example, the CHANGE ^i 
subcommand can be entered: l| 

change/apple/pear/ 

The diagonal (/) delimits the character strings APPLE and PEAR. For the 
subcommands CHANGE, LOCATE, and DSTRING, the first nonblank character 
following the subcommand name (or its truncation) is considered the 
delimiter. No blank is required following the subcommand name. In the 
subcommand: 

locate $vm/$ 

the dollar sign ($) is the delimiter. You cannot use a /in this case, 
since the diagonal is part of the character string you want to locate. 

When you enter these subcommands, you may omit the final delimiter; 
for example: 

dstring/csect 

You must enter the final delimiter, however, when you specify a global 
change with the CHANGE subcommand. 

For the FIND and OVERLAY subcommands, additional blanks following the 
subcommand names are interpreted as arguments. The subcommand: 

find Pudding 

requests the editor to locate the line that has »• Pudding" in columns 1 

through 9. Initial blanks are considered part of the character string. M 
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An asterisk, when used with an EDIT subcoimand, may mean "to the end 
of the file" or "to the record length." For example: 

delete* 
deletes all of the lines in a file, beginning with the current line. 

verify * 
indicates that the editor should display the entire length of records. 



?EDIT: 

When you make an error entering an EDIT subcommand, the editor displays 
the message: 

?EDIT: line... 

where line... is the line, as you entered it, that the editor does not 
understand- 



The Current Line Pointer 

When you begin an editing session, a file is copied into virtual 
storage; in the case of a new file, virtual storage is acquired for the 
file you are creating. In either case, you can picture the file as a 
series of records, or lines; these lines are available to you, one at a 
time, for you to modify or delete. You can also insert new lines or 
records following any line that is already in the file. 

The line that you are currently editing is pointed to by the current 
line pointer. On a display terminal, this line is highlighted. What 
you do during an editing session is: 

• Position the current line pointer to access the line you want to 
edit. 

• Edit the line: change character strings in it, delete it or insert 
new records following it. 

• Position the line pointer at the next line you want to edit. 

When you are editing a file and you issue an EDIT subcommand that 
either changes the position of the line pointer or that changes a line, 
the current line or the changed line (or lines) is displayed. You can 
also display the current line by using the TYPE subcommand: 

type 

If you want to examine more than one line in your file, you can use the 
TYPE subcommand with a numeric parameter. If you enter: 

type 10 

the current line and the nine lines that follow it are displayed; the 
line pointer then stays positioned at the last line that was displayed. 

You can move the line pointer up or down in your file. "Dp" indicates 
a location toward the beginning of the file (the first record) ; "down" 
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indicates a location toward the end of the file (the last record) . You 
use the EDIT subcomaands UP and DOWN to move the line pointer up or down 
one or more lines. For example: 

up 5 

moves the current line pointer to a line five lines closer to the 
beginning of the file, and: 

down 

moves the pointer to point at the next sequential record in the file. 

You can also request that the line pointer be placed at the 
beginning, or top of the file, or at the end, or bottom of the file. 
When you issue the subcommand: 

top 

you receive the message: 

TOF: 

and the line pointer is positioned at a null line that is always at the 
top of the file. This null line exists only during your editing session; 
it is not filed on disk when you end the editing session. 

When you issue the subcommand: 

bottom 

the current line pointer is positioned at the last record in the file. 
If you now enter input mode, all lines that you enter are appended to 
the end of the file. 

If the current line pointer is at the bottom of the file and you 
issue the DOWN subcommand, you receive the message: 

EOF: 

and the current line pointer is positioned at the end of file, following 
the last record. ^ 

When you are adding records to your file, the current line pointer is 
always pointing at the line you last entered. When you delete a line 
from a file, the line pointer moves down to point to the next line down 
in the file. 

Going from edit node to input mode does not change the current line 
pointer. If you are creating a new file and, every 30 lines or so, you 
move the current line pointer to make corrections to the lines that you 
have entered, you must issue the BOTTOM subcommand to begin entering 
more lines at the end of the file. 

The current line pointer is also moved as the result of the LOCATE 
and FIND subcommands. You use the FIND subcommand to get to a line when 
you know the characters at the beginning of the line. For example, if 
you want to change the line: 

BAXTER J.F. 065941 ACCNTNT 

you could first locate it by using the subcommand: 

find baxter 
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It you do not know the first characters on a line, you can issue the 
LOCATE subcomnand: 

locate /accntnt/ 

Both of these subcommands work only in a top-to-bottom direction: you 
cannot use them to position the line pointer above the current line. If 
you use the FIND or LOCATE subcommands and the target (the character 
string you seek) is not found, the editor displays a message, and 
positions the line pointer at the end of the file. Subsequently, if you 
reissue the subcommand, the editor starts searching at the top of the 
file. 

In a situation like that above, or in a case where you are 
repetitively entering the same LOCATE or FIUD subcommand (if, for 
example, there are many occurrences of the same character string, but 
you seek a particular occurrence) you can use the = (REUSE) subcommand. 
To use the example above, you are looking for a line that contains the 
string ONCE UPON A TIME, but you do not know that it is above the 
current line. When you issue the subcommand: 

locate /once upon a time/ 

the editor does not locate the line, and responds: 

NOT FOUND 
EOF: 

If you enter: 



the editor searches again for the same string, beginning this time at 
the top of the file, and locates the line: 

"ONCE UPON A TIME" IS A COMMON 

This may still not be the line you are looking for. You can, again, 
enter: 



The LOCATE subcommand is executed again. This time, the editor might 
locate the line: 

A STORY THAT STARTED ONCE UPON A TIME 

Figure 5 illustrates a simple CMS file, and indicates how the current 
line pointer would be positioned following a sequence of EDIT 
subcommands. 

LINE7NUMBER EDITING: Some fixed-length files are suitable for editing by 
referencing line numbers instead of character strings. The EDIT 
subcommands that allow you to change the line pointer position by line 
number are discussed under "Line-Number Editing." 
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EDIT PPRINT EXEC 



CLP 




> 


TOP: 





(null line) 


1 


5C0NTR0L OFF 


2 


SP = 


3 


&IF .&1 EQ . &EXIT 100 


4 


6FN = SI 


5 


&IF 61 EQ ? 6G0T0 -TELL 


6 


8NFN = SCONCAT $ &1 


7 


&IF .&2 EQ . &EXIT 200 


8 


8FT = 62 


9 


6FM = 63 


10 


6IF .63 NE . 6SKIP 2 


11 


6FM = A 


12 


6SKIP 3 


13 


6IF 63 NE ( 6SKIP 2 


14 


6FI! = A 


15 


6P = ( 



16 6C0NTR0L ALL 

17 COPY 6FN 6FT 6FM 6NFN 6FT A ( UNPACK 

18 PRINT 6NFN 6FT A 6P 64 65 66 67 68 69 610 6-11 612 613 614 

19 ERASE 6NFN 6FT A 

20 6EXIT 

21 -TELL 6TYPE THIS EXEC PRINTS A LISTING FROM PACKED FORMAT 
EOF: 

The line numbers represented are symbolic: they are not an actual 
part of the file, but are used below to indicate at which line the 
current line pointer is positioned after execution of the EDIT 
subcommand indicated. 



Subcommand 

DOWN 5 

OP 

LOCATE /UNP/ 

TYPE 3 

BOTTOM 

DOWN 

FIND - 

TOP 

CHANGE /EQ/EQ/ 6 

DELETE 2 

INPUT * 



CLP Position 



-> 

•> 5 
•> 4 
-> 17 

> 19 
■> 21 
•> EOF: 

> 21 
■> 

> 5 

■> 7 (lines numbered 5 and 6 are deleted) 
■> the line just entered (between 7 and 8) 



Figure 5. Positioning the Current Line Pointer 



Verification and Search Columns 



There are two EDIT subcommands you can use to control what you and the 
editor "see" in a file. The VERIFY subcommand controls what you see 
displayed; the ZONE subcommand controls what columns the editor 
searches. Normally, when you edit a file, every request that you make 
of the editor results in the display of one or more lines at your 
terminal. If you do not want to see the lines, you can specify: 

verify off 
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Alternatively, if you want to see only particular columns in a file, you 
can specify the columns you wish to have displayed: 

verify 1 30 

Some filetypes have default values set for verification, which 
usually include those columns in the file that contain text or data, and 
exclude columns that contain sequence numbers. If a verification column 
is less than the record length, you can specify: 

verify * 

to indicate that you want to see all columns displayed. 

In conjunction with the VERIFY subcommand, you can use the ZOUE 
subcommand to tell the editor within which columns it can search or 
modify data, flhen you issue the subcommand: 

zone 20 30 

The editor ignores all text in columns 1-19 and 31 to the end of the 
record when it searches lines for LOCATE, CHANGE, ALTER, and FIMD 
subcommands. You cannot unintentionally modify data outside of these 
fields; you must change the zones in order to operate on any other data. 

The zone setting also controls the truncation column for records when 
you are using the CHANGE subcommand; for more details, see "Setting 
Truncation Limits." 



Changing, Deleting, and Adding Lines 

You can change character strings in individual lines of data with the 
CHANGE subcommand. A character string may be any length, or it may be a 
null string. Any of the characters on your terminal keyboard, including 
blanks, are valid characters. The following example shows a simple data 
line and the cumulative effect of CHANGE subcommands. 

ABC ABC ABC 

is the initial data line. 

CHANGE /ABC/XYZ/ 

changes the first occurrence of the character string "ABC" to the 
string "XYZ". 

XYZ ABC ABC 

CHANGE /ABC// 

deletes the character string "ABC" and concatenates the characters 
on each side of it. 

XYZ ABC 

CHANGE //ABC/ 

inserts the string "ABC" at the beginning of the line. 

ABCXYZ ABC 

CHANGE /XYZ /XYZ/ 

deletes one blank character following "XYZ". 

ABCXYZ ABC 
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CHANGE /C/C / 

adds a blank following the first occurrence of the character "C". 

ABC XYZ ABC 

is the final line. 

THE ALTER SUBCOMMAND: You can use the ALTER subcommand to change a 
single character; the ALTER subcommand allows you to specify a 
hexadecimal value so that you can include characters in your files for 
which there are no keyboard equivalents. Once in your file, these 
characters appear during editing as nonprintable blanks. For example, 
if you input the line: 

IF A = B THEN 
in edit mode and then issue the subcommand: 

alter = 8c 
the line is displayed: 

IF A B THEN 

If you subsequently print the file containing this line on a printer 
equipped to handle special characters, the line appears as: 

IF A < B THEN 

since X*8C* is the hexadecimal value of the special character <. 

Either or both of the operands on the ALTER subcommand can be 
hexadecimal or character values. To change the X^BC to another 
character, for example <, you could issue either: 

alter 8c ae 

— or -- 

alter 8c < 

THE OVERLAY SUBCOMMAND: The OVERLAY subcommand allows you to replace 
characters in a line by spacing the terminal's typing element or cursor 
to a particular character position to make character- for-character 
replacements, or overlays. For example, given the line: 

ABCDEF 
the subcommand: 

overlay xyz 
results in the line: 

XYZDEF 

A blank entered on an OVERLAY line indicates that the corresponding 
character is not to be changed; to replace a character with a blank, use 
an underscore character (_) . Given the above line, XYZDEF, the 
subcommand: 

overlay . 3 

results in: 

DE3 (The "D" is preceded by blanks in columns 1, 2, and 3.) 
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Global Changes 

You can nlake global or repetitive changes with the CHANGE and ALTER 
subcommands. On these subcommand lines, you can include operands that ^ 
indicate: 

• The number of lines to be searched for a character or character 
string. An asterisk (*) indicates that all lines, from the current 
line to the end of the file, are to be searched. 

• Whether only the first occurrence or all occurrences on each line are 
to be modified. An asterisk (*) indicates all occurrences. If you do 
not specify an asterisk, only the first occurrence on any line is 
changed. 

For example, if you are creating a file that uses the (•) special 
character (X'AF») and you do not want to use the ALTER subcommand each 
time you need to enter the •, you could use the character -^ as a 
substitute each time you need to enter a •. When you are finished 
entering input, move the current line pointer to the top of the file, 
and issue the global ALTER subcommand: 

top#alter -• af * * 

All occurrences of the character -• are changed to X'AF*. The current 
line pointer is positioned at the end of the file. 

When you use a global CHANGE subcommand, you must be sure to use the 
final delimiter on the subcommand line. For example: 

change /hannible/hannibal/ 5 

This subcommand changes the first occurrence of the string "HANNIBLE" on 
the current line and the four lines immediately following it. 

You can also make global changes with the OVERLAY subcommand, by 
issuing a REPEAT subcommand just prior to the OVERLAY subcommand. Use 
the REPEAT subcommand to indicate how many lines you want to be 
affected. For example, if you are editing a file containing the three 
lines: 

A 
B 
C 

with the current line pointer at line "A»*, issuing the subcommands: 

repeat 3 

overlay ill 

results in: 

A I I I 
Bill 
C I I I 

The current line pointer is now positioned at the line beginning with 
the character "C". 
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You delete lines from a file with the DELETE subcommand; to delete more 
than one line, specify the number of lines: 

delete 6 

Or, if you want to delete all the lines from the current line to the end 
of the file, use an asterisk (*) : 

delete * 

If you want to delete an undetermined number of lines, up to a 
particular character string, you can use the DSTRING subcommand: 

dstring /weather/ 

When this subcomnand is entered, all the lines from and including the 
current line down to and including the line just above the line 
containing the character string "WEATHER" are deleted. The current line 
pointer is positioned at the line that has "HEATHER" on it. 

If you want to replace a line with another line, you can use the 
REPLACE subcommand: 

replace ******* 

The current line is deleted and the line ••*******" is inserted in its 
place. The current line pointer is not moved. 

To replace an existing line with many new lines, you can issue the 
REPLACE subcommand with no new data line: 

replace 

The editor deletes the current line and enters input mode. 



I|ise£lin3 Li^es 

You can insert a single line of data between existing lines using the 
INPUT subcommand followed by the line of data you want inserted. For 
example: 

input * this subroutine is for testing only 

inserts a single line following the current line. If you want to insert 
many lines, you can issue the INPUT subcommand to enter input mode. 

You can also add new lines to a file by using the GETFILE subcommand. 
This allows you to copy lines from other files to include in the file 
you are editing or creating. For example: 

getfile single items c 

inserts all the lines in the file SINGLE ITEMS C immediately following 
the current line pointer. The line pointer is positioned at the last 
line that was read in. 



( 
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You could also specify: 

getfile double items c 10 25 

to copy 25 lines, beginning with the tenth line, from the file DOUBLE 
ITEMS C. 

The $MOVE and $DUP EDIT macros provide two additional ways of adding 
lines into a file in a particular position. The $MOVE macro moves lines 
from one place in a file to another, and deletes them from their former 
position. For example, if you want to move 10 lines, beginning with the 
current line, to follow a line 9 lines above the current line, you can 
enter: 

$move 10 up 8 

The $DOP macro duplicates the current line a specified number of 
times, and inserts the new lines immediately following the current line. 
For example: 

$dup 3 

creates 3 copies of the current line, and leaves the current line 
pointer positioned at the last copy. 



Describing Data File Characteristics 

When you issue the EDIT command to create a new file, the editor checks 
the filetype. If it is one of the reserved filetypes, the editor may 
assign particular attributes to it, which can simplify the editing 
process for you. The default attributes assigned to most filetypes are 
as follows: 

• Fixed-length, 80-character records 

• All alphabetic characters are translated to uppercase, regardless of 
how they are entered 

• Input lines are truncated in column 80 

• Tab settings are in columns 1, 6, 11, 16, 21, ... 51, 61, and so on, 
and the tab characters are expanded to blanks 

• Records are not serialized 

The filetypes for some CMS commands and for the language processors 
deviate from these default values. Some of the attributes assigned to 
files and how you can adjust them to suit your needs are discussed 
below. 



RECORD LENGTH 

You can specify the logical record length of a file you are creating on 
the EDIT command line: 

edit new file (Irecl 130 
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If you do not specify a record length, the editor assumes the 
following defaults: 

• For editing old files, the existing record length is used. 

• For creating new files, the following default values are in effect: 

liletipe lecord Length Format 

EXEC 80 characters Variable 

FREEFORT 81 characters Variable 

LISTING 121 characters Variable 

SCRIPT 132 characters Variable 

VSBDATA 132 characters Variable 

All others 80 Fixed 

If you edit a variable-length file and the existing record length is 
less than the default for the filetype, the record length is taken from 
the default value. 

When you use the LRECL option of the EDIT command you can override 
these default record lengths; you can also change the record lengths of 
existing files to make them larger, but not smaller. 

If you try to override the record length of an existing file and make 
it smaller, the editor displays an error message, and you must issue the 
EDIT command again with a larger record length. For example, suppose 
you have on your B-disk a file named MYFILE FREEFORT, which was created 
with the default record length of 81. If you try to edit that file by 
issuing: 

edit myfile freefort b (Irecl 72 

the editor displays the message: 

GIVE A LARGER RECORD LENGTH. 

You must then issue the EDIT command again and either specify a length 
of 81 or more, or allow it to default to the current record length of 
the file. 

You can use the COPYFILE command to increase or decrease the record 
length of a file before you edit it. For example, if you have 
fixed-length, 132-character records in a file, and you want to truncate 
all the records at column 80 and create a file with 80-character 
records, you could issue the command: 

I copyfile extra funds a (Irecl 80 

The largest record you can edit with the editor is 160 characters. A 
file with record length up to 160 bytes (for example, a listing file 
created by a DOS program) can be displayed and edited. 

The largest record you can create with the CMS editor, however, is 
130 characters using a 3270 display terminal and 134 characters using a 
typewriter terminal such as a 2741 or 1050. If you enter more than 130 
characters on a 3270, the record is truncated to 130 characters when you 
press the Enter key. Note that as the line is truncated to 130 
characters, the CMS editor will not know the actual line length entered, 
and will not issue the "TRUNCATED'* messgae. If you type more than 134 
characters on a line using a typewriter terminal, CP generates an 
attention interruption to your virtual machine and the input line is 
lost when you press the Return key. 
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For most purposes, you will not need to create records longer than 
130 characters. If it is necessary, however, you can expand a record 
that you have entered. You do this by issuing the CHANGE subcommand 
with operands, to add more characters to the record (for example, by 
changing a 1-character string to a 31-character string) . 

YOU cannot create a record that is longer than the record length of 
the file. For example, if the file you are editing has a default record 
length of 80, or if you specified LRECL 80 when you created the file, 
the editor truncates all records to 80 characters. 



I6C2£^ liSMtii SM Zii§ Size 



There is a relationship between the record length of a file and the 
maximum number of records it can contain. Figure 6 shows the 
approximate number of records, rounded to the nearest hundred, that the 
editor can handle in a virtual machine with different amounts of virtual 
storage. 



> 





Record 
Length 


1 Virtual Machine Size | 
1 1 




1 320K 


512K 


1 768K 


1024K 1 
1 


1 80 


Characters 


1 1700 


3800 


1 6800 


9800 1 
1 


1 120 


Characters 


1 1100 


2600 


1 4700 


6800 1 
1 


1 132 


Characters 


1 1100 


2400 


1 4300 


6200 1 
1 


1 160 


Characters 


1 900 


2000 


1 3600 


5100 1 
1 










. 





Figure 6. Number of Records Handled by the Editor 



RECORD FORMAT 



With the CMS editor, you can create either fixed- or variable-length 
files. Except for the filetypes EXEC, LISTING, FREEFORT, SCRIPT, and 
VSBDATA, all the files you create have fixed-length records, by default. 
You can change the format of a file at any time during an editing 
session by using the RECFM subcommand: 

recfm v 

This changes the record format to variable-length. This does not change 
the record length; in order to add new records with a greater length, 
you must write the file onto disk and then reissue the EDIT command 
using the LRECL option. 

The COPYFILE command also has an RECFM option, so that you can change 
the record format of a file without editing it. The command: 

copyfile * requests a1 (recfm v trunc 

changes the record formats of all the files with a filetype of REQUESTS 
on your A-disk to variable-length. The TRUNC option specifies that you 
want trailing blanks removed from each of the records. When you are 
editing a file with variable-length records, trailing blanks are 
truncated when you write the file onto disk with the FILE or SAVE 
subcommand. (In VSBDATA files, however, blanks are not truncated.) 
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USING SPECIAL CHARACTERS 



The IMAGE and CASE subcoimands control how data, once entered on an 
input line, is going to be represented in a file. The specific 
characters affected, and the subcommands that control their 
representation, are: 

• Alphabetic characters: CASE subcommand 

• Tab characters (X»05»): IMAGE subcommand (ON and OFF operands) 

• Backspaces (XM6»): IMAGE subcommand (CANON operand) 



AlJEhabetic Characters 



If you are using a terminal that has only uppercase characters, you do 
not need to use the CASE subcommand; all of the alphabetic characters 
you enter are uppercase. On terminals equipped with both uppercase and 
lowercase letters, all lowercase alphabetic characters are converted to 
uppercase in your file, regardless of how you enter them. If you are 
creating a file and you want it to contain both uppercase and lowercase 
letters you can use the subcommand: 

case m 

The "M»» stands for "mixed." This attribute is not stored with the file 
on disk. If you create a new file, and you issue the CASE M subcommand, 
all the lowercase characters you enter remain in lowercase. If you 
subsequently file the file and later edit it again, you must issue the 
CASE M subcommand again to locate or enter lowercase data. 

There are two reserved filetypes for which uppercase and lowercase is 
the default. These are SCRIPT and MEMO, both of which are text or 
document-oriented filetypes. For most programming applications, you do 
not need to use lowercase letters. 



Tab Characters 



Logical tab settings indicate the column positions where fields within a 
record begin. These logical tab settings do not necessarily correspond 
to the physical tab settings on a typewriter terminal. What happens 
when you press the Tab key on a typewriter terminal depends on whether 
the image setting is on or off. The default for all filetypes except 
SCRIPT is IMAGE ON. You can change the default by issuing the 
subcommand: 

image off 

If the image setting is on, when you press the Tab key the editor 
replaces the tab characters with blanks, starting at the column where 
you pressed the Tab key, and ending at the last column before the next 
logical tab setting. The next character entered after the tab becomes 
the first character of the next field. For example, if you enter: 

tabset 1 15 



and then enter a line that begins with a tab character, the first data 
character following the tab is written into the file in column 15, 
regardless of the tab stop on your terminal. 



( 
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If the image setting is off, the tab character, X*05*, is inserted in 
the record, just as any other data character is inserted. No blanks are 
inserted. 

If you want to insert a tab character (X'05») into a record and the 
image setting is on, you can do one of the following: 

1. Set IMAGE OFF before you enter or edit the record, and then use the 
Tab key as a character key. 

2. Enter some other character at the appropriate place in the record, 
and then use the ALTER subcommand to alter that character to a 
X'05«. 

SETTING TABS; When you create a file, there are logical tab settings in 
effect, so that you do not need to set them. The default values for the 
language processors correspond to the columns used by those processors. 
If you want to change them, or if you are creating a file with a 
nonreserved filetype, you may want to set them yourself. Use the TABSET 
subcommand, for example: 

tabset 1 12 20 28 72 

Then, regardless of what physical tab stops are in effect for your 
terminal, when you press the Tab key with image setting ON, the data you 
enter is spaced to the appropriate columns. 

The default tab settings used by the editor follow. 

Filetype Default Tab Settings 

ASSEMBLE, MACRO, 1,~10, 16, 31, 36, U1, 46, 69, 72, 80, 

UPDATE, OPDTXXXX, 

ASM3705 

AMSERV 2, 6, 11, 16, 21, 26, 31, 36, 41, U6, 51, 61, 71, 80 

FORTRAN 1, 7, 10, 15, 20, 25, 30, 80 

FREEFORT 9, 15, 18, 23, 28, 33, 38, 81 

BASIC, VSBASIC 7, 10, 15, 20, 25, 30, 80 

PLIOPT, PLI 2, a, 7, 10, 13, 16, 19, 22, 25, 31, 37, U3, 49, 55, 

79, 80 

COBOL 1, 8, 12, 20, 28, 36, 44, 68, 72, 80 

All Others 1, 6, 11, 16, 21, 26, 31, 36, 41, 46, 51, 61, 71, 81, 

91, 101, 111, 121, 131 

Note: When you are specifying tab settings for files, the first tab 

setting you specify should be the column in which you want your data to 

begin. The editor will not allow you to place data in a column preceding 
this one. For example, if you issue: 

tabset 5 10 15 20 
and then enter an input line: 

input This is a line 
Columns 1, 2, 3, and 4 contain blanks; text begins in column 5. 
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For most of your applications, you do not need to underscore or 
overstrike characters or character strings. If you are using a 
typewriter terminal and are typing files that use backspaces and 
underscores, you should use either the IMAGE OFF or IMAGE CANON 
subcommands so that the editor handles the backspaces properly. IMAGE 
CANON is the default value for SCRIPT files. 

CANON means that regardless of how the characters are keyed in 
(characters, backspaces, underscores), the editor orders, or canonizes, 
the characters in the file as: character-backspace-underscore, 
character-backspace-underscore, and so on. If, for example, you want an 
input line to look like: 

ABC 
You could enter it as: 

ABC, 3 backspaces, 3 underscores 
- or - 

3 underscores, 3 backspaces, ABC 

A typewriter types out the line in the following order: 

A backspace, underscore 

B backspace, underscore 

C backspace, underscore, which results in: 

ABC 

If you need to modify a line that has backspaces, and you do not want 
to rekey all of the characters, backspaces, and overstrike characters in ({ 
a CHANGE or REPLACE subcommand, you can use the ALTER subcommand to 
alter all of the backspaces to some other character and use a global 
CHANGE command. For example, the following sequences shows how to 
delete all of the backspace characters on a line: 

alter 16 + 1 * 
_+A_+A_+A_+A_+A 
change /_+// 1 * 
AAAAA 

This technique may also be useful on a display terminal. 



SETTING TRUNCATION LIMITS 

Every CMS file that you edit has a truncation column setting: this 
column represents the last character position in a record into which you 
can enter data. When you try to input a record that is longer than the 
truncation column, the record is truncated, and the editor sends you a 
message telling you that it has been truncated. 

You can change the truncation column setting with the TRUNC 

subcommand. For example, if you are creating a file with a record length 

of 80 and wish to insert some records that do not extend beyond column 
20, you could issue the subcommand: 

trunc 20 
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Then, when you enter data lines, any line that is longer than 20 
characters is truncated and the editor sends you a message. If you are 
entering data in input mode, your virtual machine remains in input mode. 

When you use the CHANGE subcommand to modify records, the column at 
which truncation occurs is determined by the current zone setting. If 
you change a character string in a line to a longer string, and the 
resultant line extends beyond the current end zone, you receive the 
message: 

TRUNCATED. 

If you need to create a line longer than the current end zone setting, 
use the ZONE subcommand to increase the setting. The subcommand: 

zone 1 * 

extends the zone to the record length of the file. If the end zone 
already equals the record length, you have to write the file onto disk 
and reissue the EDIT subcommand specifying a longer record length. 

For most filetypes, the truncation and end zone columns are the same 
as the record length. For some filetypes, however, data is truncated 
short of the record length. The default truncation and end zone columns 
are: 

Filetxpe Column 

ASSEMBLE, MACRO 71 

UPDATE, 

UPDTXXXX 
AMSERV, COBOL, 72 

DIRECT, FORTRAN 

PLI, PLIOPT 

All Other filetypes are truncated at their record length. 

You can, when creating files for your own uses, set truncation 
columns so that data does not extend beyond particular columns. 



ENTERING A CONTINUATION CHARACTER IN COLUMN 72 

When you are using the editor to enter source records for an assembler 

language program and you need to enter a continuation character in 

column 72, or whenever you want to enter data outside a particular 

I truncation setting, you can use the following technique. Note that this 

I technique will not work if CANON is specified on the IMAGE subcommand. 

1. Change the truncation setting to 72, so that the editor does not 
truncate the continuation character: 

trunc 72 

2. Use the TABSET subcommand to set the left margin at column 72: 

ratis^t 72 

3. Use the OVERLAY subcommand to overlay an asterisk in column 72: 

overlay * 

Since the left margin is set at 72, the OVERLAY subcommand line 
results in the character * being placed in column 72. 
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4. Restore the editor truncation and tab settings: 

trunc 71 

tabset 1 10 16 31 36 41 51 61 71 81 

Note: If you issue the PRESERVE subcommand before you change the 
truncation and tab settings, then after you enter the OVERLAY 
subcommand, you can restore them with the RESTORE subcommand. See 
"Preserving and Restoring Editor Settings." 

flse the $MARK Edit Macro: Another way to insert a continuation character 
is to use the $MARK edit macro. You can find out if the SHARK edit macro 
is available on your system by entering, in the CMS or CMS subset 
environment: 

listfile $mark exec * 

If it is not available on your system, you can create the $MARK edit 
macro for your own use. See "Section 17. Writing Edit Macros" in "Part 
3. Learning to Ose EXEC." 

If you have the $MARK macro, then when you need to enter a 
continuation character, you can enter a null line to get into edit mode, 
issue the command: 

$mark 

and then return to input mode to continue entering text. 



SERIALIZING RECORDS 

Some CMS files that you create are automatically serialized for you. ^ 
This means that columns 73 to 80 of each record contain an identifier in 
the form: 

cccxxxxx 

where ccc are the first three characters of the filename and xxxxx is a 
sequence number. Sequence numbers begin at 00010 and are incremented by 
10. 

The filetypes that are automatically serialized in columns 73 to 80 
are: 



ASSEMBLE 


FORTRAN 


PLIOPT 


DIRECT 


COBOL 


UPDATE 


MACRO 


PLI 


UPDTXXXX 



You can serialize any file that has fixed-length, 80-character 
records by using the SERIAL subcommand: 

serial on 

The SERIAL subcommand can also be used to: 

• Assign a particular three-character identifier: 

serial abc 
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• Specify that all eight bytes of the sequence field be used to contain 
numbers: 

serial all 

• Specify a sequence increment other than 10: 

serial on 100 
— or — 
serial ccc 100 

• Indicate that no sequence numbers are to be assigned to new records 
being inserted: 

serial off 

When you create a file or edit a file with sequence numbers, the 
sequence numbers are not written or updated until you issue a FILE or 
SAVE subcommand. Because the end verification columns for the filetypes 
that are automatically serialized are the same as their truncation 
columns, you do not see the serial numbers unless you specify: 

verify * 

— or — 

verify 80 

Although the serial numbers are not displayed while you edit the file, 
they do appear on your output listings or printer files. 

If you are editing files with the following filetypes: 

BASIC 

VSBASIC 

FREEFORT 

the sequence numbers are on the left. For BASIC and VSBASIC files, 
columns 1-5 are used; numbers are blank-padded to the left. For 
FREEFORT files, the sequence numbers use columns 1-8, and are 
zero-padded to the left. To edit these files, you should use line-number 
editing, which is discussed next. 

LINE-NUMBER EDITING 

To edit a file by line numbers means that when you are adding new lines 
to a file or referencing lines that you wish to change, you refer to 
them by their line, or sequence numbers, rather than by character 
strings. You can use right line-number editing only on files with 
fixed-length, 80-character records. 

If you want to edit by line numbers, issue the subcommand: 

linemode right 

— or — 

linemode left 
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where "right" indicates that the sequence numbers are on the right, in 
columns 76-80, and "left" indicates you want sequence numbers on the 
left in columns 1-5. LINEMODE LEFT is the default for BASIC, VSBASIC, 
and PREEFORT files. You do not have to specify it. You must specify 
LINEMODE for files with other filetypes. 

If you specify LINEMODE RIGHT to use line-number editing on a 
typewriter terminal, the line numbers are displayed on the left, as a 
convenience, while you edit the file. 

When you are using line-number editing in input mode, you are 

prompted to enter lines; the line numbers are in increments of 10. For 

example, when you are creating a new file, you are prompted for the 
first line number as follows: 

10 

On a typewriter terminal, you enter your input line following the 10. 
When you press the carriage return, you are prompted again: 

20 

and you continue entering lines in this manner until you enter a null 
line. 

You can change the prompting increment to a larger or smaller number 
with the PROMPT subcommand: 

prompt 100 

When you are in edit mode you can locate a line by giving its line 
number: 

700 

This is the nnnnn subcommand. In line-number editing, you use it instead 
of the INPUT subcommand to insert a single line of text. For example: 

905 X = a * b 

inserts the text line "X = A * B" in the proper sequence in the file. 
If you use "nnnnn text" specifying the number of a line that already 
exists, that line is replaced; the current line pointer is moved to 
point to it. 

The EDIT subcommands that you normally use for context editing, such 
as CHANGE, ALTER, LOCATE, DP, DOWN, and so forth, can also be used when 
you are line-number editing; their operation does not change. 

RENUMBERING LINES 

When you are using line-number editing, the editor uses the prompting 
increment set by the PROMPT subcommand. However, when you begin adding 
lines of data between existing lines, the editor uses an algorithm to 
select a line number between the current line number and the next line 
number, if a prompting number cannot be generated because the current 
line number and the next line number differ only by one, the editor 
displays the message: 

RENUMBER LINES 

and you must resequence the line numbers in the file before you can 
continue line-number editing. 
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You can resequence the line numbers in one of three ways: 

1. If you are a VSBASIC or FREEFORT user, you may use the RENDM 
subcommand: 

renum 

This subcommand resolves all references to lines that are 
renumbered. 

2. If you are using right-handed line-number editing, you must: 

a. Turn off line-number editing: 

linemode off 

b. If you want to change the three-character identifier or specify 
eight-character sequence numbers, issue the SERIAL subcommand, 
for example: 

serial all 

If you want to use the default serialization setting, you do not 
need to issue the SERIAL subcommand. 

c. Issue the SAVE subcommand: 

save 

d. Reissue the LINEHODE subcommand and continue line-number 
editing: 

linemode right 

3. If you are using left-handed xine-number editing for a filetype 
other than VSBASIC or FREEFORT, you must manually change individual 
line numbers using EDIT subcommands. In order to modify the line 
numbers, you must change the zone setting and the tab setting: 

zone 1 * 
tabset 1 6 

so that you can place data in columns 1 through 6. 

When you are using right-handed line-number editing, and a FILE, 
SAVE, or automatic save request is issued, the editor does not 
resequence the serial numbers, but displays the message: 

RESERIALIZATION SUPPRESSED 

so that the lines numbers that are currently saved on disk match the 

line numbers in the file. You must cancel line-number editing (using the 

LINEHODE OFF subcommand) before you can issue a FILE or SAVE subcommand 
if you want to update the sequence numbers. 



Section 5. The CHS Editor 83 



Controlling the Editor 

There are a number of EDIT subcommands that you can use to maximize the 
use of the editor in CMS. A few techniques are suggested here; as you 
become more familiar with VM/370 and CMS you will develop additional 
techniques for your own applications. 



COMMUNICATING WITH CMS AND CP 

Often during a terminal session, you may need to issue a CMS command or 
a CP command. You can issue certain CMS commands and most CP commands 
without terminating the edit session. The EDIT subcommand CMS places 
your virtual machine in the CMS subset mode of the editor, where you can 
issue CMS commands that do not modify your virtual storage. Remember 
that the editor is using your virtual storage; if you overlay it with 
any other command or program, you will not be able to finish your 
editing. 

One occasion when you may want to enter CMS subset is when you want 
to issue a GETFILE subcommand for a file on one of your virtual disks 
and you have not accessed the disk. You can enter: 

cms 
The editor responds: 

CMS SUBSET 

Then you can enter: 

access 193 b/a \| 

return 

get setup script b 

The special CMS SUBSET command RETURN returns your virtual machine to 
edit mode. 

You can enter CP commands from CMS subset, or you can issue them 
directly from edit mode or input mode with the #CP function. For 
example, if you are inputting lines into a file and another user sends 
you a message, you can reply without leaving input mode: 

#cp m oph i will call you later 

If you enter #CP without specifying a command line, you receive the 
message: 

CP 

which indicates that your virtual machine is in the CP command 
environment, and you can issue CP commands. You would not, however, 
want to issue any CP command that would modify your virtual storage or 
alter the status of the disk on which you want to write the file. 

To return to edit or input mode from CP, use the CP command, BEGIN. 
I If you are working at a display terminal and the screen image does not 
I reappear, enter the TYPE command to cause the editor to redisplay the 
I screeni 



( 
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CHANGING FILE IDENTIFIERS 



There are several methods you can use to change a file identifier before 
writing the file onto disk- You can use the FNAME and FMODE subcoamands 
to change the filename or filemode, or you can issue a FILE or SAVE 
subcommand specifying a new file identifier. 

For example, if you want to create several copies of a file while you 
are using the editor, you can issue a series of FNAME subcommands, 
followed by SAVE subcommands, as follows: 

edit test file 
EDIT: 



fn test1#save 



p 



fn test2#save 



fn test3#file 
Or, you could issue the SAVE and FILE subcommands as follows; 
edit test file 



save test1 



save test2 



file tests 

In both of the preceding examples, when the FILE subcommand is executed, 
there are files named TEST FILE, TESTI FILE, TEST2 FILE, and TESTS FILE. 
The original TEST FILE is unchanged. 

To change the filemode letter of a disk, use the FMODE subcommand. 
You can do this in cases where you have begun editing a file that is on 
a read-only disk, and want to write it. Since you cannot write a file 
onto a read-only disk, you can issue the FMODE subcommand to change the 
mode before filing it: 

fmode a 
file 

Or, you can use the FILE (or SAVE) subcommand specifying a complete file 
identifier: 

file test file a 

You should remember, however, that when you write a file onto disk, 
it replaces any existing file that has the same identifier. The editor 
does not issue any warning or informational messages. If you are 
changing a file identifier while you are editing the file, you must be 
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careful that you do not unintentionally overlay existing files. To 
verify the existence of a file, you can enter CHS subset and issue the 
STATE or LISTFILE commands. 

CONTROLLING THE EDITOR'S DISPLAYS 

When you are using a typewriter terminal, you may not always want to see 
the editor verify the results of each of your subcommands- Particularly 
when you are making global changes, you may not want to see each line 
displayed as it is changed- You can issue the VERIFY subcommand with 
the OFF operand to instruct the editor not to display anything unless 
specifically requested. After you issue: 

verify off 

lines that are normally displayed as a result of a subcommand that moves 
the current line pointer (UP, DOWN, TOP, BOTTOM, and so forth), or that 
changes a line (CHANGE, ALTER, and so forth) , are not displayed. If the 
current line pointer moves to the end of the file, however, the editor 
always displays the EOF: message. 

If you are editing with verification off, then you must be 

particularly careful to stay aware of the position of your current line 

pointer. You can display the current line at any time using the TYPE 
subcommand: 

type 

Long and Short Error Messages: When you enter an invalid subcommand 
while you are using the editor, the editor normally responds with the 
error message: 

?EDIT: line... 

displaying the line that it did not recognize. If you prefer, you can 
issue the SHORT subcommand so that instead of receiving the long form of 
the error, you receive the short form, which is: 



Hhen you issue an invalid edit macro request (any line that begins with 
a $) , you receive the message: 

-,$ 

To resume receiving the long form of the error message, use the LONG 
subcommand: 

long 

LONG and SHORT control the display of the error message regardless of 
whether you are editing with verification on or off . 

I On a display terminal, all EDIT messages that are displayed at the 
I top of the screen, including error messages and '?EDIT:' messages, are 
I highlighted. 
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PRESERVING AND RESTORING EDITOR SETTINGS 

The PRESERVE and RESTORE subcommands are used together; the PRESERVE 
subcommand saves the settings of the EDIT subcommands that control the 
file format, message and verification display, and file identifier. If 
you are editing a file and you want to temporarily change some of these 
settings, issue the PRESERVE subcommand to save their current status. 
When you have finished your temporary edit project, issue the RESTORE 
subcommand to restore the settings. 



Section 5. The CMS Editor 86.1 



March 30, 1979 



86,2 IBM VM/370 CMS User's Guide 



) 






For example, if you are editing a SCRIPT file and want to change the 
image setting to create a particular format, you can enter: 

preserve 

image on 

tabset 1 15 UO 60 72 

zone 1 72 

trunc 72 

When you have finished entering data using these settings, you can issue 
the subcommand: 

restore 

to restore the default settings for SCRIPT filetypes. 



X, Y, =, ? SUBCOMMANDS 

The X, Y, =, and ? subcommands all perform very simple functions that 
can help you to extend the language of the CMS editor. They allow you 
to manipulate, reuse, or interrogate EDIT subcommands. 

If you have an editing project in which you have to execute the same 
subcommand a number of times, you can assign it to the X or Y 
subcommands, as follows: 

X locate /insert here/ 
y getfile insert file c 

Each time that you enter the X subcommand: 

X 

the command line LOCATE /INSERT HERE/ is executed, and every time you 
enter the Y subcommand: 

y 

the GETFILE subcommand is executed. 

When you specify a number following an X or Y subcommand, the 
subcommand assigned to X or Y is executed the specified number of times; 
for example: 

X locate /aa/ 
X 10 

the LOCATE subcommand line is executed 10 times before you can enter 
another EDIT subcommand. 

Another method of re-executing a particular subcommand is to use the 
= (REUSE) subcommand. For example, if you enter: 

locate /ard/ 
AARDVARK 



the LOCATE subcommand is re-executed seven times. 

What the = (REUSE) subcommand actually does is to stack the 
subcommand in the console stack. Since CMS, and the editor, read from 
the console stack before reading from the terminal, the lines in the 
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stack execute before a read request is presented to the terminal. When 
you enter multiple equal signs, the subcommand is stacked once for each 
equal sign you enter. 

You can also stack an additional EDIT subcommand following an equal 
sign. The subcommand line is also stacked, but it is stacked LIFO 
(last-in, first-out) so that it executes before the stacked subcommand. 
For example, if you enter: 

delete 
= next 

a DELETE subcommand is executed, then a DELETE subcommand is stacked, 
and a NEXT subcommand is stacked in front of it. Then the stacked lines 
are read in and executed. The above sequence has the same effect as if 
you enter: 

delete 

next 

delete 

In addition to stacking the last subcommand executed, you can also 
find out what it was, using the ? subcommand. For example, if you 
enter: 

next 10 
? 

the editor displays: 

NEXT 10 

Since the subcommand line NEXT 10 was the last subcommand entered, if 
you enter an = subcommand, it is executed again. You cannot stack a ? 
subcommand. 

Note: The ? subcommand, on a display terminal, copies the last EDIT 
subcommand into the user input area, where you may modify it before 
re-entering it. 



WHAT TO DO WHEN YOU RON OOT OF SPACE 



There are two situations that may prevent you from continuing an edit 
session or from writing a file onto disk. You should be aware of these 
situations, know how to avoid them, and how to recover from them, should 
they occur. 

When you issue the EDIT command to edit a file, the editor copies the 
file into virtual storage. If it is a large file, or you have made many 
additions to it, the editor may run out of storage space. If it does, it 
issues the message: 

AVAILABLE STORAGE IS NOW FULL 

When this happens, you cannot make any changes or additions to the file 
unless you first delete some lines. If you attempt to add a line, the 
editor issues the message: 

NO ROOM 



If you were entering data in input mode, your virtual machine 
returned to edit mode, and you may receive the message: 



is 
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STACKED LINES CLEARED 

which indicates that any additional lines you entered are cleared and 
will not be processed. 

You should use the FILE subcommand to write the file onto disk. If 
you want to continue editing, you should see that the editor has more 
storage space to work with. To do this, you can find out how large your 
virtual machine is and then increase its size. To find out the size, 
issue the CP QUERY command: 

cp query virtual storage 

If the response is: 

STORAGE = 256K 

You might want to redefine your storage to 51 2K. Dse the CP command 
DEFINE, as follows: 

cp define storage 512k 

This command resets your virtual machine, and you must issue the CP IPL 
command to reload the CMS system before you can continue editing. 

If a file is very large, the editor may not have enough space to 
allow you to edit it using the EDIT command. The message: 

DMSEDI132S FILE »fn ft fm« TOO LARGE 

indicates that you must obtain more storage space before you can edit 
the file. If this is the case, or if you are editing large files, you 
should redefine your storage before beginning the terminal session. If 
this happens consistently, you should see your installation support 
personnel about having the directory entry for your userid updated so 
that you have a large storage size to begin with. 

Splitting CMS Files Into Smaller Files 

If the file you are editing is too large, and the data it contains does 
not have to be in one file, you can split the file into smaller files, 
so that it is easier to work with. Two of the methods you can use to do 
this are described below. 

II§6 i^® COPYFILE Command: You can use the COPYFILE command to copy 
portions of a file into separate files, and then delete the copied lines 
from the original file. For example, if you have a file named TEST FILE 
that has 1000 records, and you want to split it into four files, you 
could enter: 

copyfile test file a testi file a (from 1 for 250 

copyfile test file a test2 file a (from 251 for 250 

copyfile test file a test3 file a (from 501 for 250 

copyfile test file a test4 file a (from 751 for 250 

When these COPYFILE commands are complete, you have four files 
containing the information from the original TEST FILE, which you can 
erase: 

erase test file 

yse the Editor: If you use the editor to create smaller files, you can 
edit them as you copy them, that is, if you have other changes that you 
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want to make to the data. To copy files with the editor, you use the 
GETFILE subcommand. Using the file TEST FILE as an example, you might 
enter: 

edit test1 file 

getfile test file a 1 250 



file 

edit test2 file 

getfile test file a 251 250 



Again, you could erase the original TEST FILE when you are through with 
your edit session. 

Ih en Your Disk Is Full 

When you enter a FILE or SAVE subcommand or when an automatic save 
request is issued, the editor writes a copy of the file you are editing 
onto disk, and names it EDIT CMSUT1. If this causes the disk to become 
full, you receive the message: 

DMSBHR170S DISK »mode(cuu)» IS FULL 

The editor erases the workfile, and issues the message: 

SET NEW FILEMODE, OR ENTER CMS SUBSET AND CLEAR SOME SPACE 

The original file (as last written onto disk) remains unchanged. You il 
can use the CMS subcommand to enter CMS subset, and erase any files that 
you do not need. You can use the LISTFILE command to list the files on 
the disk, then the ERASE command to erase the unwanted files. 

If you cannot erase any of the files on the disk, there are several 
alternate recovery paths you can take: 

1. If you have another read/write disk accessed, you can use the FMODE 
subcommand to change the filemode of the file, so that when you 
file it, it is written to the other disk. If you have a read/write 
disk that is not accessed, you can access it in CMS subset. After 
filing the file on the second disk, erase the original copy, and 
then use the COPYFILE command to transfer the file back to its 
original disk. 

2. If you do not have any other read/write disk in your virtual 
machine, you may be able to transfer some of your files to another 
user, using the PUNCH or DISK DUMP commands in CMS subset. When the 
files have been read onto the other user's disk, you can erase them 
from your disk. Then, return to edit mode and issue the FILE 
subcommand. 

3. In CMS subset, erase the original disk file (if it existed) , then 
return to edit mode and file the copy that you are editing. You 
should not use this method unless absolutely necessary, since any 
unexpected problems may result in the loss of both the disk file 
and the copy. 

After you use the FILE subcommand to write the file onto disk, you £' 
should continue erasing any files you no longer need. \^ 
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Summary of EDIT Subcommands 

The EDIT subcommands, and their formats, are shown in Figure 7. Refer to 
the VM/370 CMS Command and Macro Reference for complete details. 



\ 



1 Subcommand Format I Function 


1 r T 1 Scans the next n records of 
1 ALter char1 char2 1 n r t 1 Ithe file, altering the speci- 
1 1 * 1 G i 1 Ified character, either once in 
1 1 i 1 * 1 1 leach line or for all occur- 
1 «• L J J jrences in the line. 


1 r 1 1 Automatically saves the file 
1 AOTOsave |n | jon disk after the indicated 
1 JOFFJ 1 number of lines have been 
1 L J 1 processed. 


1 r T 1 Points the current line 
1 BAckward | nj I pointer to a line above the 
1 1 11 nine currently pointed to. 
1 *- -I t 


1 Bottom 1 Makes the last line of the 
1 Ifile the current line. 


1 r T 1 Indicates whether translation 
1 CASE 1 M 1 |to uppercase is to be done, or 
1 1 1 {displays the current status. 

1 L .1 1 


1 r r TT 1 Changes string 1 to string2 for 
1 Change [/string1[/string2[/ |n |G||]]]|n records or to EOF, either 
1 11 1*11 jfor the first occurrence in 
1 L u jj jeach line or for all 
1 1 occurrences. 


1 CMS 1 Enters CMS subset command 
1 tmode. 


I r T 1 Deletes n lines or to the end 
1 DELete I n | |of the file (*) . 
1 1*1 1 
1 111 1 

1 L J 1 


1 r T 1 Points to the nth line from 
1 Down 1 n 1 I the current line. 
1 111 1 

1 L J 1 


1 DString /[string [/]] IDeletes all lines from the 
1 1 current line down to the line 
1 1 containing the indicated 
1 1 string. 


1 FILE [fn [ft [fm]]] | Saves the file being edited on 
1 jdisk or changes its identi— 
1 jfiers. Returns to CMS. 






Figure 7. Summary of EDIT Subcommands and Macros (Part 1 of 4) 
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1 Subcommand Format | Function 


1 Find [line] • I Searches the file for the 
1 1 given line. 


1 FMode [fm] I Resets or displays the 
1 Ifilemode. 


1 FName [fn] I Resets or displays the 
1 {filename. 


1 FORMat (DISPLAY^ I Switches the 3270 terminal 
1 o3 |line / (between display mode and line 
1 Imode. (3270 only) 


1 r T 1 Points to the nth line after 
1 Forward | n I I the current line. 
1 1 1 1 1 

1 L J 1 


1 r r rrTTTT I Inserts a portion or all of 
1 Getfile fn | ft | fm | m | n | | | I |the specified file after the 
1 1 1 111*1111 1 current line. 

1 C L LLJJJJj 


1 r T 1 Expands text into line images 
1 IMAGE jON 1 |or displays current settings. 
1 lOFF 1 1 
1 1 CANON 1 1 

1 L J 1 


1 Input [line] 1 Inserts a line in the file or 
1 1 enters input mode. 


1 r T (Sets or displays current 
1 LlNEmode jLEFT 1 1 setting of line-number 
1 1 RIGHT 1 1 editing. 
1 lOFF 1 1 

1 L J 1 


1 [ Locate ]/[ string [/]] I Scans file from next line for 
1 1 first occurrence of 'string*. 


1 LONG 1 Enters long error message 
1 {mode. 


1 r T IPoints to the nth line down 
1 Next 1 n 1 jfrom the current line. 

1 1 1 1 1 
1 t J 1 


1 Overlay [line] {Replaces all or part of the 
1 {current line. 


{ PREserve {Saves current mode settings. 


{ r 1 {Sets or displays line number 
{ PROMPT jn { {increment. Initial setting is 
{ {10{ {10. 

( L J 1 



Figure 7. Summary of EDIT Subcommands and Macros (Part 2 of 4) 
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i Subcommand Format | Function 


1 QUIT 1 Terminates edit session with 
1 |no updates incorporated since 
1 ilast save request. 


1 r T jSets or displays record format 
1 RECfm 1 F 1 Ifor subsequent files. 
1 1 V 1 1 

1 L J 1 


1 r r m | Recomputes line numbers for 
1 RENuffl Istrtno |incrno|| IVSBASIC and FREEFORT source 
1 110 Istrtno II 1 files. 

1 L L JJ 1 


1 r 1 1 Executes the following OVERLAY 
1 REPEAT 1 n 1 1 subcommand n times. 
1 1*1 1 
1 111 1 

1 L J 1 


1 Replace [line] I Replaces the current line or 
1 1 deletes the current line and 
1 1 enters input mode. 


1 REStore | Restores editor settings to 
1 lvalues last preserved. 


1 RETURN 1 Returns to edit environment 
1 Ifrom CMS subset. 


ITREUSE) [subcommand] | Stacks (LIFO) the last EDIT 
it = j 1 subcommand that does not start 
1 |with REUSE or the question 
1 Imark (?) and then executes any 
1 1 given EDIT subcommand. 


1 SAVE [fn [ft [fm]]] 1 Saves the file on disk and 
1 1 stays in edit environment. 


1 r 1 1 Displays a number of screens 
1 f scroll \ In 1 jof data above or below the 
1 ts[croll]U[p]/ 1* 1 {current line (3270 only). 
1 11 1 1 

1 L J 1 


1 SERial { OFF r t ) | Turns serialization on or off 
1 ) ON liner 1 f |in columns 73 through 80. 
1 ) ALL 1 10 1 ( 1 
1 ( seq «- J j 1 


1 SHORT 1 Enters short error message 
1 Imode. 


1 r T 1 Stacks data lines or EDIT 
1 STACK in 1 1 subcommands in the console 
1 1 1 1 1 input stack. 
1 1 1 1 
1 Isubcommandl t 

1 L J 1 



m 



Figure 7. Summary of EDIT Subcommands and Macros (Part 3 of 4) 
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1 Subcommand Format | Function 


1 TABSet n1 [n2 ... nn] I Sets logical tab stops. 


1 TOP 1 Moves the current line pointer 
1 |to the null line at the top 
1 |of the file. 


1 r T ISets or displays the column of 
1 TRUNC 1 n 1 1 truncation. An asterisk (*) 
1 1*1 1 indicates the logical record 
1 «- J 1 length. 


i r r 1 n I Displays m lines beginning 
1 Type 1 m 1 n 1 1 I with the current line. Each 
1 111*11 1 line may be truncated to n 
1 1*1 II 1 characters. 

1 L L J J 1 


1 r T 1 Moves the current line pointer 
1 Dp 1 n 1 1 toward the top of the file. 
1 1 1 1 1 

1 L J 1 


1 r 1 rr t t |Sets, displays^ or resets 
1 Verify |0N | | jstartcoljendcol | | verification. An asterisk (*) 
1 JOFFJ II 1 1 * 1 1 indicates the logical record 
1 L J LL J J {length. 


j r T 1 Assigns to X or Y the given 
1 rx^ 1 subcommand! I EDIT subcommand or executes 
1 \Yj 1 n 1 jthe previously assigned 
1 1 1 1 1 subcommand n times. 

1 L J 1 


1 r r T T {Sets or displays the columns 
1 zone 1 m i n 1 j 1 between which editing is to 
1 1 1 1 * 1 1 Itake place. 
11*111 1 

1 t. L J J 1 


1 ? {Displays the last EDIT 

1 1 subcommand, except = or ?. 


1 f nnnnn ) [text] {Locates the line specified by 
1 \nnnnnnnn) {the given line number and 
{ (inserts text, if given. 


{ r T {Duplicates the current line n 
1 $DUP 1 n ( {times. $DUP is an edit macro. 
1 1 1 1 1 

( L J 1 


i $MOVE n f Up m J (Moves up n lines or down m 

{ } Down m > (lines. SHOVE is an edit macro. 

{ ( TO label j { 



Figure 7. Summary of EDIT Subcommands and Macros (Part 4 of 4) 
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An EXEC is a CMS file that contains executable statements. The 
statements may be CHS or CP commands or EXEC control statements. The 
execution can be conditionally controlled with additional EXEC 
statements, or it may contain no EXEC statements at all. In its simplest 
form, an EXEC file may contain only one record, have no variables, and 
expect no arguments to be passed to it. In its most complex form, it can 
contain thousands of records and may resemble a program written in a 
high-level programming language. As a CHS user, you should trecome 
familiar with the EXEC processor and use it often to tailor CHS commands 
to your own needs, as well as to create your own commands. 

The following is an example of a simple EXEC procedure that might be 
named RDLIHKS EXEC: 

CP LINK DEWEY 191 291 RR DEWEY 
CP LINK LIBRARY 192 292 RR DEWEY 
ACCESS 291 B/A 
ACC 292 C/A 

When you enter: 

rdlinks 

each command line contained in the file RDLINKS EXEC is executed. 

You could also create an EXEC procedure that functions like a 
cataloged procedure, and set it up to receive an argument, so that it 
executes somewhat differently each time you invoke it. For example, a 
file named ASH EXEC contains the following: 

ASSEHBLE &1 
PRINT 61 LISTING 
LOAD &1 
START 

If you invoke the EXEC specifying the name of an assembler language 
source file, such as: 

asm myprog 

the procedure executes as follows: 

ASSEHBLE HYPROG 
PRINT HYPROG LISTING 
LOAD HYPROG 
START 

The variable £1 in the EXEC file is substituted with the argument you 
enter when you execute the EXEC. As many as 30 arguments can be passed 
to an EXEC in this manner; the variables thus set range from 81 through 
830- 



CREATING EXEC FILES 

EXEC files can be created with the CHS editor, by punching cards, or by 
using CHS commands or programs. When you create a file with the editor. 
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records are, by default, variable-length with a logical record length of 
80 characters. EXEC can process variable-length files of up to 130 
characters. To create a variable-length EXEC file larger than 80 
characters, use the LRECL option of the EDIT command: 

edit new exec a (Irecl 130 

To convert a variable-length file to a fixed-length file, you can 
edit the EXEC file and issue the subcommand: 

recfm f 

Or, you can use the COPYFILE command: 

copyfile old exec a (recfm f 

If you use fixed-length EXEC files, you should be aware that the EXEC 
interpreter only processes the first 72 characters of each record in a 
fixed-length file, regardless of the record length. You can, however, 
enter command or data lines that are longer than than 72 characters to 
be processed by using the SBEGSTACK, SBEGTYPE, 6BEGP0NCH, and SBEGEMSG 
control statements preceding the line (s) you want to be processed. If 
you specify SBEGPONCH ALL, EXEC processes lines up to .80 characters 
long; if you specify &BEGTYPE ALL, &BEGSTACK ALL, or SBEGEMSG ALL, EXEC 
processes lines up to 130 characters. 

In variable-length EXEC files, there are no such restrictions; lines 
up to 130 characters are processed in their entirety. 

Two CMS commands create EXEC files. One is LISTFILE, which can be 
invoked with the EXEC option; it creates a file named CMS EXEC. The uses 
of CMS EXEC files are discussed under the heading "CMS EXECs and How To 
Ose Them." The CMS/DOS command LISTIO creates an EXEC file named 
$LISTIO EXEC, which creates records for each of the system and 
programmer logical unit assignments. The LISTIO command and the $LISTIO 
EXEC are described in "Section 9. Developing DOS Programs Under CMS." 



INVOKING EXEC FILES 

EXEC procedures are invoked when you enter the filename of the EXEC 
file. You can precede the filename on the command line with the CMS 
command, EXEC. For example: 

exec test type list 

where TEST is the filename of the EXEC file and TYPE and LIST are 
arguments (SI, S2, and so on) you are passing to the EXEC- For example, 
an EXEC named PREPEDIT would be executed when you entered either: 

prepedit newfile replace 

— or — 

exec prepedit newfile replace 

You must precede the EXEC filename with the EXEC command when: 

• You invoke an EXEC from within another EXEC. 

• You invoke an EXEC from a program. 

• You have the. implied EXEC function set off for your virtual machine. 



( 
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The implied EXEC function is controlled by the SET coamand. If you 
issue the command: 

set impex off 

then you must use the EXEC command to invoke an EXEC procedure. The 
default setting is ON; you almost never need to change it. 

There is one EXEC file that you never have to specifically invoke. 
This is a PROFILE EXEC, which is automatically executed after you load 
CMS, when your A-disk is accessed. PROFILE EXECs are discussed next. 



PROFILE EXECs 

A PROFILE EXEC must have a filename of PROFILE. It can contain the CP 
and CMS commands you normally issue at the start of every terminal 
session. For example: 

• Commands that describe your terminal characteristics, such as: 

CP SET LINEDIT ON 
SET BLIP * 
SET RDYMSG SMSG 
SYNONYM MYSYN 

• Commands that spool your printer and punch for particular classes or 
characteristics: 

CP SPOOL E CLASS S HOLD 

• Commands to initialize macro and text libraries that you commonly 
use: 

GLOBAL MACLIB OSMACRO CMSLIB 
GLOBAL TXTLIB PRIVLIB 

• Commands to access disks that are a permanent part of your 
configuration: 

ACCESS 196 B 

A PROFILE EXEC file that contains all of these commands might look 
like this: 

&CONTROL OFF 

CP SET LINEDIT ON 

CP SPOOL E CLASS S HOLD 

SET RDYMSG SMSG 

SET BLIP * 

SYNONYM MYSYN 

GLOBAL MACLIB OSMACRO CMSLIB 

GLOBAL TXTLIB PRIVLIB 

ACCESS 196 B 

SCONTROL OFF is an EXEC control statement that specifies that the CP 
and CMS command lines are not to be displayed on your terminal before 
they execute. 

A PROFILE EXEC can be as simple or as complex as you require. As an 
EXEC file, it can contain any valid EXEC control statements or CBS 
commands. The only thing that makes it special is its filename. 
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PROFILE, which causes it to be executed the first time you press the 
Return key after loading CMS. 



EXECUTING YOUR PROFILE EXEC 

Usually, the first thing you do after loading CMS is to type a CMS 
command. When you press the Return key to enter this command or if you 
enter a null line, CMS searches your A-disk for a file with a filename 
of PROFILE and a filetype of EXEC. If such a file exists, it is 
executed before the first CMS command you enter is executed. Because 
you do not do anything special to cause your PROFILE EXEC to execute, 
you can say that it executes "automatically." 

You can prevent your PROFILE EXEC from executing automatically by 
entering: 

access (noprof) 

as the first CMS command after you IPL CMS. You can enter: 

profile 

at any time during a CMS session to execute the PROFILE EXEC, if you had 

accessed your A-disk without it, or if you had made changes to it and 

wanted to execute it, or if you had changed your virtual machine and 
wanted to restore its original characteristics. 



CMS EXECs and How to Use Them 

A file named CMS EXEC is created when you use the EXEC option of the 
LISTFILE command; for example: 

listfile pr* document a (exec 

The usual display that results from this LISTFILE command is a list of 
all the files on your A-disk with a filetype of DOCUMENT that have 
filenames beginning with the characters "PR". CMS, however, creates a 
CMS EXEC file that contains a record for each file that would be listed. 
The records are in the format: 

SI S2 filename filetype filemode 

Column 1 is blank. Now, if you have the following files on your A-disk: 

PRFILE1 DOCUMENT 
PRFILE2 DOCUMENT 
PRFILE3 DOCUMENT 
PRFILE4 DOCUMENT 

The CMS EXEC file would contain the records: 

&^ &2 PRFILE1 DOCUMENT Al 

S1 82 PRFILE2 DOCUMENT Al 

S1 82 PRFILE3 DOCUMENT Al 

81 82 PRFILE4 DOCUMENT Al 
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In the preceding lines, &1 and S2 are variables that can receive values 
from arguments you pass to the EXEC when you execute it. For example, 
if you execute this CMS EXEC by issuing: 

cms disk dump 

the EXEC interpreter substitutes, on each line, the variable &1 with the 
DISK and the variable &2 with DUMP and executes the commands: 

DISK DUMP PRFILE1 DOCUMENT A1 

DISK DUMP PRFILE2 DOCUMENT A1 

DISK DUMP PHFILE3 DOCUMENT Al 

DISK DUMP PRFILE4 DOCUMENT Al 

You can use this technique to transfer a number of files to another 
user. You should remember to spool your punch with the CONT option 
before you execute the EXEC, so that all of the files are transferred as 
a single spool file; for example: 

cp spool d cont library 

Then, after executing the EXEC file, close the punch: 

cp spool d nocont close 

If you pass only one argument to your CMS EXEC file, the variable 82 
is set to a null string. For example: 

cms erase 

executes as: 

ERASE PRFILE1 DOCUMENT Al 

ERASE PRFILE2 DOCUMENT A1 

ERASE PRFILE3 DOCUMENT Al 

ERASE PRFILEU DOCUMENT Al 

You could also use a CMS EXEC to obtain a listing of files on a 

virtual disk. If you want, you can use one of the other LISTFILE command 

options with the EXEC option to get more information about the files 
listed. For example: 

listfile * * a (exec date 

produces a CMS EXEC that contains, in addition to the filename, 
filetype, and filemode of each file listed, the file format and size, 
and date information. You can then use the PRINT command to obtain a 
printed copy: 

print cms exec 

Before printing this file, you may want to use the SORT command to 
sort the list into alphabetic order by filename, by filetype, or both; 
for example: 

sort cms exec a cmssort exec a 

When you are prompted to enter sort fields, you can enter: 

1 25 

The file CMSSORT EXEC that is created contains a completely alphabetical 
list. 
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MODIFYING CMS EXECS 

A CMS EXEC is like any other CMS file; you can edit it, erase it, rename 
it, or change it. If you have created it to catalog a particular group 
of files, you might want to rename it; each time you use the LISTFILE 
command with the EXEC option a CMS EXEC is created, and any old CMS EXEC 
is erased. To rename it, you can use the CMS RENAME command, or, if you 
are editing it, you can rename it when you file it: 

edit cms exec 
input Scontrol off 
file prfile exec 

YOU might also want to edit a CMS EXEC to provide it with more 
numeric variables; for example: 

edit ens exec 

input Scontrol off 

input cp spool printer class s cont 

change /a1/a1 S3 S4 S5 S6/ * 



input cp spool printer nocont 
input cp close printer 
file prfile exec 
prfile print % (cc 

When this EXEC is executed, the variable SI is substituted with PRINT, 
the variable &2 is set to a null string (the special character % 
indicates that you are not passing an argument to it) , and 63 and S4 are 
set to the PRINT command option (CC, so that the files in the EXEC print 
with carriage control. The CP commands that are inserted ensure that 
the files print as a single spool file, and not individually. 



Summary of the EXEC Language Facilities 

The EXEC processor, or interpreter, recognizes keywords that begin with 
the special character ampersand (S) - Keywords may indicate: 

• Control statements 

• Built-in functions 

• Special variables 

• Arguments 

You may also define your own variables in an EXEC file; the EXEC 
interpreter can process them as long as they begin with an ampersand. 
The following pages briefly discuss the kinds of things you can do with 
an EXEC, introduce you to the control statements, built-in functions, 
and special variables, and give some examples of how to use the EXEC 
processor. If you want more information on writing EXEC procedures, see 
"Part 3. Learning To Dse EXEC." For specific information on the format 
and usage rules for any EXEC statement or variable, consult the VM/370 
CMS Command and Macro Reference. 

In general the following rules apply to entering lines into an EXEC 
procedure: 

1. Most input lines (with a few exceptions) are scanned during 
execution of the EXEC. Every word on a line is padded or truncated 
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to fit into an eight-character "token." So, for example, if you 
enter the EXEC control statement: 

8type today is Wednesday 

when this EXEC is executed, the line is displayed at your terminal: 

TODAY IS WEDNESDA 

The lines that are not tokenized are those that begin with an * 
(and are considered comments) , and those that follow an SBEGEHSG, 
SBEGPONCH, &BEGSTACK, or &BEGTYPE control statement, up to an SEND 
statement. 

2. YOU can enter input lines beginning in any column. The only tine 
that you must enter an EXEC line beginning in column 1 is when you 
are using the &END control statement to terminate a series of lines 
being punched, stacked, or typed. 



ARGUMENTS AND VARIABLES 

Host EXEC processing is contingent on the value of variable expressions. 
A variable expression in an EXEC is a symbol that begins with an 
ampersand (6). When the EXEC interpreter processes a line and 
encounters a variable symbol, it substitutes the variable with a 
predefined value, if the symbol has been defined. Symbols can be 
defined in three ways: (1) when passed as arguments to the EXEC, (2) by 
assignment statements, (3) interactively, as a result of a BREAD ARGS or 
8READ VARS control statement. 

You can pass arguments to EXEC files when you invoke them. Each 
argument you enter is assigned a variable name: the first argument is 
81, the second is 82, the third is 83, and so on. You can assign values 
for up to 30 variables this way. For example, if an EXEC is invoked: 

scan alpha 2 notype print 

the variable 81 has a value of ALPHA, the variable 82 has a value of 2, 
83 is NOTYPE and 84 is PRINT- These values remain in effect until you 
change them. 

You can test the arguments passed in several ways. The special 
variable 8INDEX contains the number of arguments received. Using the 
example SCAN ALPHA 2 NOTYPE PRINT, the statement: 

8IF 8INDEX EQ 4 8G0T0 -SET 

would be true, since four arguments were entered, so a branch to the 
label -SET is taken. 

You can change the values of arguments or assign values using the 
8ARGS control statement. For example: 

8IF 8INDEX EQ 8ARGS ABC 

assigns the values A, B, and C to the variables 81, 82, and 83 when the 
EXEC is invoked without any arguments. 

Use the 8READ ARGS control statement to enter arguments 
interactively. For example, if your EXEC file contains the line: 

8READ ARGS 
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when this line is executed, the EXEC issues a read to your virtual 
machine so that you can enter up to 30 arguments, to be assigned to the 
variables S1, &2, and so on* 



ASSIGNMENT STATEMENTS 



User-defined variable names begin with an ampersand {&) and contain up 
to seven additional characters* These variables can contain numeric or 
alphameric data. You define and initialize EXEC variables in assignment 
statements. In an assignment statement, the first data item starts with 
an ampersand (S) and the second data item is an equal sign (=) - The 
value of the expression on the right side of the equal sign is assigned 
to the variable named on the left of the equal sign. For example: 

SA = 35 

is an assignment statement that assigns the numeric value 35 to the 
variable symbol SA. A subsequent assignment statement might be: 

SB = SA + 10 

After this assignment statement executes, the value of SB would be 35 
plus 10, or 45- 

You can use the 8READ control statement to assign variable names 
interactively. For example, when the statement: 

SREAD VARS SNAHE SAGE 

is executed, the EXEC issues a read to your virtual machine, and you can 
enter a line of data. The first two words, or tokens, you enter are 
assigned to the variable symbols SNAME and SAGE, respectively. 

Note; The data item immediately following the target of an assignment 
statement must be an equal sign (=) and not an EXEC variable that has 
the value of an equal sign,. Conversely, if an equal sign is to be the 
first data item following an EXEC control word, then it must be 
specified as an EXEC variable that has the value of an equal sign and 
not as an equal sign; otherwise, the statement is interpreted as an 
assignment statement and the control word is thereafter treated as a 
variable. 



Null Variables 



If you use a variable name that has not been defined, the variable 
symbol is set to a null string by the EXEC processor when the statement 
is executed. For example, if you have entered only two arguments on the 
EXEC command line, then the statement: 



SIF S3 EQ CONT SERROR SCONTINOE 

is interpreted: 

SIF EQ CONT SERROR SCONTINUE 

SERROR and SCONTINOE are recognized by EXEC as control statements. 
Since S3 is undefined, however, it is replaced by blanks and the 
resulting line produces an error during EXEC processing. You can 
prevent the error, and allow for null arguments or variables, by 



( 
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concatenating some other character with the variable. A period is used 
Bost frequently: 

GIF .63 EQ .CONT &ERROR &COIITINOE 
l£ &3 is undefined when this line is scanned, the result is: 

SIF . EQ .CONT SERROR SCONTINUE 
Which is a valid control statement line. 

BOILT-IN FOKCTIONS AND SPECIAL VARIABLES 

The EXEC tuilt-in functions are similar to those of higher-level 
languages. You can use the EXEC built-in functions to define variable 
symbols in an EXEC procedure. 

Figure 8 summarizes the built-in functions. It shows, given the 
variable &A, the values resulting in a variable &B when a built-in 
function is used to assign its value. Notice that all of the built-in 
functions are used on the right-hand side of assignment statements. Only 
the &LITERAL built-in function can be used in control statements; for 
example: 

STYPE &LITERAL SA 



Function I Usage 



I Example 



&6 



SCONCAT 

1 SDATATYPE 

&LENGTH 

&LITERAL 

8S0BSTR 



Concatenates tokens into a 

single token. 
Assigns the data type (NOM 

or CHAR) to the variable. 
Assigns the length of a 

token to a variable. 
Prohibits substitution of a 

variable symbol. 
Extracts a character string 

from a token. 



I &A 
1 


= 


123 


1 

1 &B 
1 


= 


SCONCAT GA 55 


1 

i &6 


- 


SDATATYPE SA 


1 

1 &B 

1 


= 


SLENGTH SA 


1 

1 SB 
1 


= 


SLITERAL SA 


1 

1 &6 


= 


SSUBSTR SA 2 2 



12355 

NOM 

3 

SA 

23 



Figure 8. Summary of EXEC Built-in Functions 



FLOW CONTROL IN AN EXEC 
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An EXEC is processed line by line: if a statement is encountered that 
passes control to another line in the procedure, execution continues 
there and each line is, again, executed sequentially. You can pass 
control with an SGOTO control statement: 

SGOTO -BEGIN 

Where -BEGIN is a label. All labels in EXEC files must begin with a 
hyphen, and must be the first token on a line. For example: 

-LOOP 
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A label may have control statements or commands following it; for 
example: 

-HERE SCONTINUE 

which indicates that the processing is to continue with the next line, 
or: 

-END &EXIT 

The SEXIT control statement indicates that the EXEC processor should 
terminate execution of the EXEC and return control to CHS. You can also 
specify a return code on the SEXIT control statement: 

SEXIT 6 

results in a "(00006)" following the "R" in the CMS ready message. If 
you invoke a CMS command from the EXEC, you can specify that the return 
code from the CMS command be used: 

SEXIT SRETCODE 

Since the SRETCODE special variable is set after each CMS command that 

is executed, you can test it after any command to decide whether you 

want execution to end. For example, you could use the SIF control 
statement to test it: 

SIF SRETCODE NE SEXIT SRETCODE 

"SEXIT SRETCODE" places the value of the CMS return code in the CMS 
ready message. You could place a line similar to the above following 
each of your CMS command lines, or you could use the SERROR control 
statement, that will cause an exit as soon as an error is encountered: 

SERROR SEXIT SRETCODE 

or you could use the SERROR control statement to transfer control to 
some other part of your EXEC: 

SERROR SGOTO -CHECK 



-CHECK 



Another way to transfer control to another line is to use the SSRIP 
control statement: 

SSKIP 10 

transfers control to a line that is 10 lines below the SSKIP line. You 
can transfer control above the current line as well: 

SIF SX NE SY SSKIP -3 

Transferring control with SSKIP is faster, when an EXEC is executing, 
than it is with SGOTO, but modifying your EXEC files becomes more 
difficult, particularly when you add or delete many lines. 
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You can use combinations of SIF, &GOTO, and 6SKIP to set up loops in 
an EXEC. For example: 

SX = 1 

SIF SX = U 8G0T0 -ENDPRT 

PRINT FILE6X TEST A 

SX = SX + 1 

SSKIP -3 

-ENDPRT 

or, you can use the SLOOP control statement: 

SX = 1 

SLOOP 2 SX > 3 
PRINT FILESX TEST 
SX = SX ♦ 1 

-ENDPRT 

In both of these examples, a loop is established to print the files 
FILE1 TEST, FILE2 TEST, and FILE3 TEST. SX is initialized with a value 
of 1 and then incremented within the loop. The loop executes until the 
value of SX is greater than 3. As soon as this condition is met, control 
is passed to the label -ENDPRT. 



COMPARING VARIABLE SYMBOLS AND CONSTANTS 

In an EXEC, you can test whether a certain condition is true, and then 
perform some function based on the decision. Some examples have already 
appeared in this section, such as: 

SLOOP 3 SX EQ SY 

In this example, the value of the variable SX is tested for an equal 
comparison with the value of the variable SY. The loop is executed until 
the condition (SX equal to SY) is true. 

The logical comparisons you can make are: 

Condition HfieSSSic Symbol 

equal Iq = 

not equal NE -•= 

greater than GT > 

less than LT < 
greater than 

or equal to GE >= 
less than or 

equal to LE <= 

When you are testing a condition in an EXEC file, you can use either the 
mnemonic or the symbol to represent the condition: 

SIF SA LT SB SGOTO -NEXT 

is the same as: 

SIF SA < SB SGOTO -NEXT 
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DOING I/O WITH AN EXEC 

You can communicate with your terminal using the 8TYPE and 8READ control 
statements. Use 8TYPE to display a line at your terminal: 

&TYPE ASHBLNG &1 ASSEMBLE 

When this line is processed, if the variable 61 has a value of PROGI, 
the line is displayed as: 

ASNBLNG FR0G1 ASSEMBLE 

Use the BREAD control statement when you want to be able to enter 
data, variables, or control statements into your EXEC file while it is 
executing. If you use it with an 8TYPE statement, for example: 

8TYPE DO YOU WANT TO CONTINUE ? 
SREAD VARS SANS 

you could test the variable SANS in your EXEC to find out how processing 
is to continue. 

The SBEGTYPE control statement can be followed by a sequence of lines 
you want to be displayed at the terminal. For example, if you want to 
display ten lines of data, instead of using ten 8TYPE control 
statements, you could use: 

&BEGTYPE 

line1 

line2 



linelO 4 

SEND '^ 

The SEND control statement indicates the end of the lines to be typed. 
You can also use the SBEGTYPE control statement when you want to type a 
line that contains a word with more than eight characters in it; for 
example: 

SBEGTYPE 

TODAY IS WEDNESDAY 

SEND 

The EXEC interpreter, however, does not perform substitutions on lines 
entered this way. The lines: 

SA = DOG 

SBEGTYPE 

MY SA IS NAMED FIDDLEFADDLE 

SEND 

result in the display: 

MY SA IS NAMED FIDDLEFADDLE 

You must use the STYPE statement when you want to display variable data; 
you must use the SBEGTYPE control statement to display words with more 
than eight characters. 



To type null or blank lines at your terminal (to make output 
readable, for example), you can use the SSPACE control statement: 

SSPACE 5 
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Osina Your Virtual Card Punch 



You can punch lines of tokens into your virtual card punch with the 
SPDNCH control statement: 

&PUNCH SNAME &T0TA1 

ihen you want to punch more than one line of data, or a line that 
contains a word of more than eight characters in it, you should use the 
SBEGPUNCH control statement preceding the lines you want to punch, and 
follow them with an SEND statement. The EXEC processor does not 
interpret these lines, however, so any variable symbols you enter on 
these lines are not substituted. 

When you punch lines from an EXEC procedure what you are actually 
doing is creating a file in your virtual card punch. To release the 
file for processing, you must close the punch: 

cp close punch 

The destination of the file depends on how you have spooled your punch. 
If you have spooled it to yourself, the file is placed in your virtual 
card reader, and you can read it onto a virtual disk using the READCARD 
command. 



Stacking Lines 

The EXEC control statements 8STACK and 5BEGSTACK allow you to stack 

lines in your terminal console, to be executed as soon as a read occurs 

in your virtual machine. Stacking is useful when you use commands that 
require responses, for example, the SORT command: 

6STACK 1 20 

SORT IHFILE FILE A OOTFILE FILE A 

When the SORT command is executed, a prompting message is issued, the 
virtual machine read occurs, and the response that you have stacked is 
read. If you do not stack a response to this command, your EXEC does 
not continue processing until you enter the response from your terminal. 

I In the above example of the SORT command, you can suppress the 

I prompting message by issuing the SSTACK HT command immediately before 

I the SORT command. Restore normal terminal operations by placing an 

I &STACK RT command after the SORT command. 

Stacking is useful in creating edit macros or in editing files from 
EXEC procedures. 



MONITORING EXEC PROCEDURES 

Two EXEC control statements, 8C0NTR0L and STIME, control how much 
information is displayed at your terminal while your EXEC file is 
executing. This display is called an execution summary. 

Since you do not usually receive a CMS ready message after the 
execution of each CMS command in an EXEC, you do not receive the timing 
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information that is provided with the ready nessage. If you want this 
timing information to appear, you can specify: 

STIME ON 

or you can type the CPU times at particular places by using: 

STIME TYPE 

The SCONTROL control statement allows you to specify whether certain 
lines or types of information are displayed during execution. By 
default, CP and CMS commands are displayed before they are executed. If 
you do not wish to see them displayed, you can specify: 

SCONTROL OFF 

You might find it useful, when you are debugging your EXECs, to use: 

SCONTROL ALL 

Hhen you use this form, all EXEC statements, as well as all CP and CHS 
commands, are displayed and you can see the variable substitutions being 
performed and the branches being taken in a procedure. 



( 
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Summary of EXEC Control Statements and Special 
Variables 

Figures 9 and 10 summarize EXEC control statements and special 
variables. 



1 1 

1 Control Statement | Function | 


1 Svariable = ^string | I Assigns a value to the symbol | 
1 Jae f 1 specif ied by Svariable; the j 
1 J function! j equal sign must be preceded | 
1 (x*xxxxxx) land followed by a blank. | 


1 SARGS [argi [arg2 — [arg30]]] | Redefines the variable symbols! 
j j&1, S2... with the values of j 
1 I'argi', «arg2*, ..., and re— | 
1 jsets the variable SINDEX. 1 


1 SBEGEMSG [ALL] I Displays the following lines j 
1 linel las CBS error messages, without 1 
1 line2 j scanning them. I 
i . 1 1 
1 . 1 1 
1 SEND 1 1 


1 &BEGPUNCH [ALL] | Punches the following lines | 
1 linel jin the virtual card punch, | 
I line2 j without scanning them. j 
1 . 1 1 
1 . 1 1 
1 &END 1 1 


1 r T r n | Stacks the following lines I 
1 &BEGSTACK IFIFOj |ALL| |in the console input buffer, | 
1 linel ILIFOI »• -« | without scanning them. | 
1 line2 •- j 1 I 

i . 1 1 
1 . 1 i 
1 SEND 1 1 


1 &BEGTYPE [ALL] | Displays the following lines | 
I linel |at the console, without I 
i line2 Iscanning them. 1 
1 . 1 i 
1 . 1 1 
1 SEND 1 1 


1 &CONTINUE 1 Provides a branch address for j 
I JSERROR, 6G0T0, and Other con— j 
1 jditional branching statements.! 



Figure 9. Summary of EXEC Control Statements (Part 1 of 3) 
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Control Statement 



Function 



SCONTROL 

r TT TT t r T 

I OFF I |MSG I I TIME | I PACK | 

I ERROR I iNOHSGi |NOTIHE| |NOPACK| 

I CMS I L J C ~ J L J 
(ALL i 

L J 



6EMSG mmmnnns [tokl [...tokn]] 



&END 



r T 

8EHR0R I executable—statement I 

ISCONTINfil I 

L J 



r 1 

6EXIT I return-code I 



8G0T0 



TOP 

linenumber 

-label 



SHEX {ON ) 
roFF] 



SIF rtok1 




tok2 \ executable- 
> statement 



SLOOP 



rn Wm I 
\ -label / ( condition / 



&PDNCH [tokl [...tokn]] 



Sets, until further notice, 
the characteristics of the 
execution summary of the EXEC, 
which is displayed at the 
console. 



Displays a line of tokens 
as a CMS error message. 



Terminates a series of lines 
following an 8EEGEMSG, 
8BEGP0NCH, SBEGSTACK, or 
SBEGTYPE control statement. 



Executes the specified 
statement whenever a CHS 
command returns a nonzero 
return code. 



Exits from the EXEC file with 
the given return code. 



Transfers control to the top 
of the EXEC file, to the given 
line, or to the line starting 
with the given label. 



Turns on or off hexadecimal 
conversion. 



Executes the specified 
statement if the condition is 
satisfied. 



Loops through the following n 
lines, or down to (and includ- 
ing) the line at label, for 
ffl times, or until the 
condition is satisfied. 



Punches the specified tokens 
to your virtual card punch. 



Figure 9. Summary of EXEC Control Statements (Part 2 of 3) 



c 
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1 " ' " ... ... 

1 Control Statement | Function 


1 r T 1 Reads lines from the terminal 
j &READ In 1 jor from the console stack. 
1 IJ 1 lARGS assigns the tokens read 
1 lARGS 1 |to the variables &1, &2 ... 
1 jVARS [&var1 [ . ..8var17 ] ]| jVARS assigns the tokens read 
1 «- J |to the specified variable 
1 Isymbols. 


i r T 1 Transfers control forward or 
1 &SKIP 1 n 1 1 backward a specified number 
1 1 1 t |of lines. 
1 •- ~ -" 1 


1 r T 1 Displays blank lines at the 
1 &SPACE 1 n 1 j terminal. 
1 1 i 1 1 
1 •- -• 1 


1 r T r T 1 Stacks a line in the terminal 
1 SSTACK IFIFOI |tok1 [... tokn]| linput stack. 
1 ILIFOI |HT 1 1 
1 t J |BT 1 1 
1 «• ■» 1 


1 r T 1 Displays timing information 
I 8TIHE jON 1 1 following the execution of 
1 lOFF 1 ICHS commands. 
1 IRESETj 1 
1 ITYPE 1 1 
1 •- -» 1 


1 STYPE [tok1 [...tokn]] 1 Displays a line at the 
I (terminal. 



Figure 9. Summary of EXEC Control Statements (Part 3 of 3) 
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1 Variable { 


Usage 


Set By 


1 &n 1 


Arguments passed to an EXEC are assigned to 
the variables SI through S30. 


Oser 


1 S* 1 
1 &$ 1 


Test whether all (6*) or any (S$) of the 
arguments passed to EXEC have a particular 
value. 


EXEC 


1 6DISKX 1 


Indicates whether the disk access at mode 'x* 
is a CMS OS, or DOS disk, or not accessed 
(CMS, OS, DOS, or NA) . 


User 


1 8DISK* 1 


Contains the mode letter of the first read/write 
disk in the CMS search order, or NONE if no 
read/write disk is accessed. 


Oser 


1 8DISK? 1 


Contains the mode letter of the read/write disk 
with the most available space or NONE, if no 
read/write disk is accessed. 


Oser 


1 &DOS 1 


Indicates whether or not the CMS/DOS environment 
is active (ON or OFF) . 


Oser 


i SEXEC 1 


Contains the filename of the EXEC file currently 
being executed- 


EXEC 


1 &GLOBAL 1 


Has a value ranging from 1 to 19, to indicate 
the recursion (nesting) level of the EXEC that 
is currently executing. 


EXEC 


i GGLOBALn I 


The variables SGLOBALl through SGL0BAL9 can 
contain integral numeric values, and can be 
passed among different recursion levels. If 
not explicitly set, the variable will have a 
value of 1.. 


Oser 


1 &INDEX 1 


Contains the number of arguments passed to 
the EXEC on the command line or the number of 
arguments entered as a result of an &ARGS or 
SREAD ARGS control statement. 


EXEC 


1 SLINENDM 1 


Contains the current line number in the EXEC. 


EXEC 


1 &READFLA6 | 


Indicates whether (STACK) or not (CONSOLE) 
there are lines stacked in the terminal input 
buffer (console stack) . 


EXEC 


1 SRETCODE 1 


Contains the return code from the most recently 
executed CMS command. 


CMS 


1 6TYPBFLAG | 


Indicates whether (RT) or not (HT) output is 
being displayed at the console. 


EXEC 


i &0 1 


Contains the name of the EXEC file- 


Oser 


i Key ; 

joser: Variat 
lEXEG: You ms 
ICMS; You ma 
1 compl€ 


)les are assigned values by EXEC but you may modif; 
ly not modify these variables. 

ly assign a value to this variable but it is reset 
Jtion of each CMS command. 


f them, 
at the 



Figure 10. EXEC Special Variables 
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Section 7. Using Real Printers, Punches, 
Readers, and Tapes 



CMS Unit Record Device Support 

CMS supports one virtual card reader at address OOC, one virtual card 
punch at address OOD, and one virtual printer at address OOE, When you 
invoke a CMS command or execute a program that uses one of these unit 
record devices, the device must be attached at the virtual address 
indicated. 



USING THE CP SPOOLING SYSTEM 

Any output that you direct to your virtual card printer or punch, or any 
output you receive through your card reader, is controlled by the 
spooling facilities of the control program (CP) . Each output unit is 
known to CP as a spool file, and is queued for processing with the spool 
files of other users on the VM/370 system. Oltimately, a spooled 
printer file or a spooled punch file may be released to a real printer 
or card punch for printing or punching. 

The final disposition of a unit record spool file depends on the 
spooling characteristics of your virtual unit record devices, which you 
can alter with the CP command SPOOL. To find out the current 
characteristics of your unit record devices you can issue the command: 

cp query ur 

You might see, as a response to this, the display: 

RDR OOC CL A NOCONT NOHOLD EOF REAEY 
PON OOD CL A NOCONT NOHOLD COPY 01 REALY 

OOD FOR CMSGDE DIST 13SCRIPT 
PRT OOE CL A CONT HOLD COPY 01 READY 

OOE FOR CMSGDE DIST 13SCRIPT 

Some of these characteristics, and the ways you can modify them, are 
discussed below. ¥hen you use the SPOOL command to control a virtual 
unit record device, you do not change the status of spool files that 
already exist, but rather set the characteristics for subsequent output. 
For information on modifying existing spool files, see "Altering Spool 
Files," below. 

CLASS (CL) : Spool files, in the CP spool file queue, are grouped 
according to class, and all files of a particular class may be processed 
together, or directed to the same real output device. The default 
values for your virtual machine are set in your VM/370 directory entry, 
and are probably the standard classes for your installation. 

You may need, however, to change the class of a device if you want a 
particular type of output, or some special handling for a spool file. 
For example, if you are printing an output file that requires special 
forms, and your installation expects that output to be spooled class Y, 
issue the command: 

cp spool printer class y 
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All subsequent printed output directed to ycur printer at virtual 
address OOE (all CMS output) is processed as class Y. 

HOLD; If you place a HOLD on your printer or punch, any files that you 
print or punch are not released to the control program's spooling queue 
until you specifically alter the hold status. By placing your output 
spool files in a hold status, you can select which files you print or 
punch, and you can purge duplicate or unwanted files. To place printer 
and punch output files in a hold status issue the commands: 

cp spool printer hold 
cp spool punch hold 

Note; When you issue a SPOOL command for a unit record device, you can 
refer to it by its virtual address, as well as by its generic device 
type (for example, CP SPOOL E HOLD). 

When you have placed a hold status on printer or punch files and you 
produce an output file for one of these devices, CP sends you a message 
to remind you that you have placed the file in a hold: 

PRT FILE xxxx FOR userid COPY xx HOLD 
If, however, you have issued the command; 

cp set msg off 

then you do not receive the message. 

Hhen you place a reader file in a hold status, then the file remains 
in the card reader until you remove the hold status and read it, or you 
purge it. 

COPY; If you want multiple copies of a spool file, you should use the 
COPY operand of the SPOOL command; 

cp spool printer copy 10 

If you enter this command, then all subsequent printer files that you 
produce are each printed 10 times, until you change the COPY attribute 
of your printer. 

FOR; You can spool printed or punched output under another userid's name 
by using the FOR operand of the SPOOL command. For example, if you 
enter; 

cp spool printer for Charlie 

Then, all subsequent printer files that you produce have, on the output 
separator page, the userid CHARLIE and the distribution code for that 
user. The spool file is then under the control of that user, and you 
cannot alter it further. 

CONT, NOCONT; You can print or punch many spool files, but have them 

print or punch as one continuous spool file if you use the CONT operand 

on the SPOOL command. For example, if you issue the following sequence 
of commands: 

cp spool punch cont to brown 

punch asmi assemble 

punch asm2 assemble 

punch asmS assemble 

cp spool punch nocont 

cp close punch 
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Then, the three files ASMI ASSEMBLE, ASM2 ASSEMBLE, and ASM3 ASSEMBLE, 
are punched to user BROHN as a single spool file. When user BBOHN reads 
this file onto a disk, however, CMS creates separate disk files. 

TO: When you spool your printer or punch to another userid, all output 
from that device is transferred to the virtual card reader of the userid 
you specify- When you are punching a CMS disk file, as in the example 
above, you should use the TO operand of the SPOOL command to specify the 
destination of the punch file. 



You can also use this operand to place 
card reader by using the * operand: 

cp spool printer to * 



output in your own virtual 



After you enter this command, subsequent printed output is placed in 
your virtual card reader. You might use this technique as an alternative 
way of preventing a printer file from printing, or, if you choose to 
read the file onto disk from your reader, of creating a disk file from 
printer output. 

Similarly, if you are creating punched output in a program and you 
want to examine the output during testing, you could enter: 

cp spool punch to * 

so that you do not punch any real cards or transfer a virtual punch file 
to another user. 



ALTERING SPOOL FILES 



) 



After you have requested that VM/370 print or punch a file, or after you 
have received a file in your virtual card reader and before the file is 
actually printed, punched, or read, you can alter some of its 
characteristics, change its destination, or delete it altogether. 



Every spool file in the VM/370 system has a unique four-digit number 
from to 9900 assigned to it, called a spoolid. You can use the spoolid 
of a file to identify it when you want to do something to it. You can 
also change a group of files, by specifying that all files of a 
particular class be altered in some way, or you can manipulate all of 
your spool files for a certain device at the same time. 

The CP commands that allow you to manipulate spool files are CHANGE, 
ORDER, PURGE, and TRANSFER- In addition, you can use the CP QUERY 
command to list the status and characteristics of spool files associated 
with your userid. 

When you use any of these commands to reference spool files of a 
particular device, you have the choice of referring to the files by 
class or by spoolid. You can also specify ALL. For example, if you 
enter the command: 

cp query printer all 

you might see the display: 






ORIGINID FILE CLASS RECDS CPY HOLD DATE TIME NAME 
SCARLET 0211 D PRT 000140 01 USER 07/09 10:25:23 TARA 
SCARLET 0245 A PRT 000026 01 NONE 07/09 10:25:41 CMSLIB 



TYPE DIST 
FILE BIN015 
MACLTB BIN015 
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Until any of these files are processed, or in the case of files in the 
hold status, until they are released, you can change the spool file name 
and spool file type (this information appears on the first page or first 
card of output) , the distribution code, the number of copies, the class, 
or the hold status, using the CP CHANGE command. For example: 

cp change printer all nohold 

changes all printer files that are in a hold status to a nohold status. 
The CP CHANGE command can also change the spooling class, distribution 
code, and so on. 

If you decide that you do not want to print a particular printer 
file, you can delete it with the CP PURGE command: 

cp purge printer 7615 

After you have punched a file to some other user, you cannot change 
its characteristics or delete it unless you restore it to your own 
virtual reader. You can do this with the TRANSFER command: 



cp transfer all from usera 

This command returns to your virtual card reader all punch files that 
you spooled to USERA* s virtual card reader. 

You can determine, for your reader or printer files, in what order 
they should be read or printed. If you issue the command: 

cp order printer 8195 6547 

Then, the file with spoolid of 8195 is printed before the file with a 
spoolid of 6547. 

The CP spooling system is very flexible, and can be a useful tool, if 
you understand and use it properly. The VM/370 CP Command Reference for 
General Users contains complete format and operand descriptions for the 
CP commands you can use to modify spool files. 



USING YOUR CARD PUNCH AND CARD READER IN CMS 



The CMS READCARD command reads cards from your virtual card reader at 
address OOC. Cards can be placed in the reader in one of two ways: 

• By reading real punched cards into the system card reader. A CP ID 
card tells the CP spooling system which virtual card reader is to 
receive the card images. 

• By transferring a file from another virtual machine. Cards are 
transferred as a result of a virtual punch or printer being spooled 
with the TO operand, or as a result of the TRANSFER command. Virtual 
card images are created with the CMS PUNCH command, or from user 
programs or EXEC procedures. 



fisina Real Cards 



If you have a deck of punched cards that you want read into your virtual 
machine card reader, you should punch, preceding the deck, a CP ID card: 

ID HAPPY 



( 
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If you plan to use the READCARD command to read this file onto a CHS 
disk, you can also punch a READ control card that specifies the filename 
and filetype you want to have assigned to the file: 

:READ FR0G6 ASSEMBLE 
Then, to read this file onto your CHS A-disk, you can enter the command: 

readcard * 

If a file named PR0G6 ASSEMBLE already exists, it is replaced. 

If you do not punch a READ control card, you can specify a filename 
and filetype on the READCARD command: 

readcard prog6 assemble 

If this spool file contained a READ control card, the card is not read, 
but remains in the file; if you edit the file, you can use the DELETE 
subcommand to delete it. 

If a file does not have a READ control card, and if you do not 
specify a filename and filetype when you read the file, CHS names the 
file READCARD CMS0T1. 

If you are reading many files into the real system card reader, and 
you want to read them in as separate spool files (or you want to spool 
them to different userids) , you must separate the cards and read the 
decks onto disk individually. The CP system, after reading an ID card, 
continues reading until it reaches a physical end of file. 

Dsinq Your Virtual Card Punch 

When you use the CHS PUNCH command to punch a spool file, a READ control 
card is punched to precede the deck, so that it can be read with the 
READCARD command. If you do not wish to punch a READ control card (also 
referred to as a header card) , you can use the NOHEADER option on the 
PUNCH command: 

punch progS assemble * ( noheader 

Tou should use the NOHEADER option whenever you punch a file that is not 
going to be read by the READCARD command. 

The PUNCH command can only punch records of up to 80 characters in 
length. If you need to punch or to transfer to another user a file that 
has records greater than 80 characters in length, you can use the DISK 
DUMP command: 

disk dump prog9 data 

If your virtual card punch has been spooled to another user, that user 
can read this file using the DISK LOAD command: 

disk load 

Unlike the READCARD command, DISK LOAD does not allow you to specify a 
file identification for a file you are reading; the filename and 
filetype are always the same as those specified by the DISK DUMP command 
that created the spool file- 

A card file created by the DISK DUMP command can only be read onto 
disk by the DISK LOAD command. 

Section 7. Using Real Printers, Punches, Readers, and Tapes 117 



Using the MQVEFIL E Command 

You can use the MOVEFILE command, in conjunction with the FILEDEF 
command, to place a file in your virtual card reader, or to copy a file 
from your card reader to another device. For example: 

cp spool punch to * 

filedef punch punch 

filedef input disk coffee exec a1 

movefile input punch 

the file COFFEE EXEC Al is punched to your virtual card punch (in 
card-image format) and spooled to your 0¥n virtual reader. 



Creating Files Osing Your Reader and Punch 

Apart from the procedures shown above, that transfer whole files with 
one or two commands, there are other methods you can use to create files 
using your virtual card punch. From a program or an EXEC file, you can 
punch one line at a time to your virtual punch. Then use the CLOSE 
command to close the spool file: 

cp close punch 

Depending on how the punch was spooled (the TO setting) , the virtual 
punch file is either punched or transferred to a virtual card reader. 

PUNCHING CARDS USING 1^0 MACROS; If you write an OS, DOS, or CBS program 
that produces punched card output, you should make an appropriate file 
definition- If you are an OS User, you should use the FILEDEF command ./] 
to define the punch as an output data device; if you are a DOS user, you ^ 
must use the ASSGN command. If you are using the CMS PDNCHC macro, the 
punch is assigned for you. The spooling characteristics of your virtual 
punch control the destination of the punched output. 

PUNCHING CARDS FROM AN EXEC: The EXEC facilities provide two control 
statements for punching cards: 8P0NCH, which punches a single line to 
the virtual card punch, and SBEGPONCH, which precedes a number of lines 
to be punched. You can also, in an EXEC, use the commands PUNCH and 
DISK DUMP to punch CMS files. 



Handling Tape Files in CMS 

There are a variety of tape functions that you can perform in CMS, and a 
number of commands that you can use to control tape operations or to 
read or write tape files. One of the advantages of placing files on 
tapes is portability: it is a convenient method of transferring data 
from one real computing system to another. In CMS, you can use tapes 
created under other operating systems. There are also two CMS commands, 
TAPE and DDR, that create tape files in formats unigue to CMS, that you 
can use to back up minidisks or to archive or transfer CMS files. 

Under VM/370, virtual addresses 181 through 184 are usually reserved 
for tape devices. In most cases, you can refer to these tapes in CMS by 
using the symbolic names TAP1 through TAP4. In any event, before you 
can use a tape, you must have it mounted and attached to your virtual 
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machine by the system operator. When the tape is attached, you receive 
a message. For example, if the operator attaches a tape to your virtual 
machine at virtual address 181, you receive the message: 

TAPE 181 ATTACHED 

The various types of tape files, and the commands and programs you 
can use to read or write them are: 

TAPE Command; The CMS TAPE command creates tape files from CMS disk 
files. They are in a special format, and should only be read by the CMS 
TAPE LOAD command. For examples of TAPE command operands and options, 
see "Using the CMS TAPE Command." 

TAPPDS Command: The TAPPDS command creates CMS disk files from OS or DOS 
sequential tape files, or from OS partitioned data sets. 

TAPEMAC Command: The TAPEMAC command creates CMS MACLIB files from OS 
macro libraries that were unloaded onto tape with the lEHMOVE utility 
program. 

MOVEFILE Command: The MOVEFILE command can copy a sequential tape file 
onto disk or a disk file onto tape. Or, it can move files from your 
card reader to tape or from tape to your card punch. 

User Proarams: You can write programs that read or write sequential tape 
files using OS, DOS, or CMS macros. 

Access Method Services; Tapes created by the EXPORT function of access 
method services can be read only using the access method services IMPOST 
function. Both the IMPORT and EXPORT functions can be accomplished in 
CHS using the AMSERV command. The access method services REPRO function 
can also be used to copy sequential tape files. 

]Q£S Program: The DDR program, invoked with the CMS command DDR, dumps 
the contents of a virtual disk onto tape, and should be used to restore 
such files to disk. 



USING THE CMS TAPE COMMAND 

The CMS TAPE command provides a variety of tape handling functions- It 
allows you to selectively dump or load CMS files to and from tapes, as 
well as to position, rewind, and scan the contents of tapes. You can 
use the TAPE command to save the contents of CMS disk files, or to 
transfer them from one VM/370 system to another. The following example 
shows how to create a CMS tape with three tape files on it, each 
containing one or more CMS files, and then shows how you, or another 
user, might use the tape at a later time. 

The example is in the form of a terminal session and shows, in the 
"Terminal Display" column, the commands and responses you might see. 
System messages and responses are in uppercase, and user-entered 
commands are in lowercase. The "Comments" column provides explanations 
of the commands and responses. 
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Terminal Display 
TAPE 181 ATTACHED 

listfile * assemble a (exec 

R; 

cms tape dump 

TAPE DOMP PR0G1 ASSEMBLE Al 

DUMPING . 

PB0G1 ASSEMBLE Al 

TAPE DUMP PR0G2 ASSEMBLE Al 

DUMPING 

PB0G2 ASSEMBLE Al 

TAPE DUMP PR0G3 ASSEMBLE Al 



Comments 

Message indicates that the tape is 
attached. 

Prepare to dump all ASSEMBLE files 
by using the LISTFILE command EXEC 
option; then execute the CMS EXEC 
using TAPE and DUMP as arguments. 

The TAPE command responds to each 
TAPE DUMP by printing the file 
identification of the file being 
dumped. 



TAPE DUMP PR0G9 ASSEMBLE Al 


DUMPING 




PR0G9 ASSEMBLE 

R; 

tape wtm 

R; 

tape dump mylib m< 


Al 




aclib a 


DUMPING 




MYLIB MACLIB 

R; 

tape dump cmslib ] 


Al 


Daclib * 


DUMPING 




CMSLIB MACLIB 

R; 

tape wtm 


S2 




R; 




tape dump mylib txtlib a 


DUMPING 




MYLIB TXTLIB 

R; 

tape wtm 2 


Al 




R; 




tape rew 




R; 




tape scan (eof 4 




SCANNING.,... 




PB0G1 ASSEMBLE 


Al 


PB0G2 ASSEMBLE 


Al 


PR0G3 ASSEMBLE 


Al 


PB0G4 ASSEMBLE 


Al 


PROGS ASSEMBLE 


Al 


PB0G6 ASSEMBLE 


Al 


PR0G7 ASSEMBLE 


Al 


PR0G8 ASSEMBLE 


Al 


PR0G9 ASSEMBLE 


Al 



END-OF-FILE OR END-OF-TAPE 
MYLIB MACLIB Al 
CMSLIB MACLIB S2 
END-OF-FILE OR END-OF-TAPE 
MYLIB TXTLIB Al 
END-OF-FILE OR END-OF-TAPE 
END-OF-FILE OR END-OF-TAPE 

R; 

#cp det 181 

TAPE 181 DETACHED 



The last file, PE0G9 ASSEMBLE, is 
dumped. 



The TAPE command writes a tape mark 
to indicate an end of file. 

Two macro libraries are dumped, 

by specifying the file identifiers 



Another tape mark is written. 
A TEXT library is dumped. 



Two tape marks are written to 

indicate the end of the tape. 
The tape is rewound. 

The tape is scanned to verify 
that all of the files are on it. 



Tape mark indication. 



Two tape marks indicate the end 
of the tape. 

The CP DETACH command rewinds 
and detaches the tape. 



< 
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Terainal Disjolay Comments 

******** 

* 

* The tape created above is going to be read. 

* 



TAPE 181 ATTACHED 

tape load progU assemble 

LOADING 

PR0G4 ASSEMBLE A1 

R; 

tape scan 

SCANNING 

PROGS ASSEMBLE Al 
PR0G6 ASSEMBLE Al 
PR0G7 ASSEMBLE A1 
PR0G8 ASSEMBLE Al 
END-OF-FILE OR END-OF-TAPE 

R; 

tape scan 

SCANNING.... 

MYLIB MACLIB Al 

CMSLIB MACLIB S2 

END-OF-FILE OR END-OF-TAPE 

R; 

tape bsf 2 

R; 

tape fsf 

R; 

tape load (eof 2 

LOADING 

MYLIB MACLIB A1 
CMSLIB MACLIB A2 
END-OF-FILE OR END-OF-TAPE 
MYLIB TXTLIB A1 
END-OF-FILE OR END-OF-TAPE 

R; 

#cp detach 181 
TAPE 181 DETACHED 



Message indicating the tape is 
attached. 

One file is to be read onto disk. 

The TAPE command displays the 
name of the file loaded. Any 
existing file with the same 
filename and filetype is erased. 

The remainder of the first tape 
file is scanned. 



Indication of end of first tape file, 
The second tape file is scanned. 



The tape is backed up and 

postioned in front of the 

last tape file. 
The tape is forward spaced past 

the tape mark. 
The next two tape files are 

going to be read. 



The tape is detached. 



Tape Labels in CMS 

Support in the CMS component of VM/370 to process labelled tapes 
includes the following features; 

• Checks IBM standard labels on input 

• Writes IBM standard labels on output 

• Allows you to specify routines to process standard user labels during 
DOS and OS macro simulation under CMS 

• Allows you to specify exits for processing tapes with nonstandard 
labels during execution of CMS macro simulations and some CMS tape 
operation commands 
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CMS processes all tape labels; CP does not process tape labels. 
Limitati ons 

CMS tape label processing does not include: 

• Label processing for tapes that are read backwards 

• Processing of multivolume files on tapes 

• Support for ANSI tapes or ASCII labels 

• Label processing for any functions of the CMS TAPE command except the 
two functions DY0L1 and W70L1 that' process VOLl labels 

USER RESPONSIBILITIES 

You must initiate all your own tape label processing. To specify that 
you have a la,belled tape, use the FILEDEF command for an OS simulation 
program, or use a DOS DTFMT macro for a CMS/DOS program- You can also 
use the TAPE$L macro to process standard HDR1 and E0F1 labels and the 
CMS TAPE ccj^mmand to write and display standard V0L1 labels- You can 
provide IBM/ standard label description details with the LABELDEF command 
for all ty/pes of label processing. After label processing has been 
requested,/ it occurs automatically and there is no interaction between 
you and CMS unless an error occurs- See the "Error Processing" section 
later in this publication for a discussion of error processing- 

LABEL PROCESSING IN OS SIMULATION 

If you are running an OS simulation program and using OPEN and CLOSE 
macros, you specify the type of label processing you want in a FILEDEF 
command for a given file- Detailed information about the FILEDEF 
command is found in the VM/370 CMS Command and Macro Reference. You may 
specify that you want standard label processing (with SL) or nonstandard 
label processing (with NSL) . If you choose nonstandard label 
processing, you must already have written a routine to process 
nonstandard labels. The name of this routine must be specified by the 
filename in the NSL parameter on FILEDEF. An example of nonstandard 
label processing is given in the section "NSL Processing". To be sure 
that the tape you are using contains no IBM labels, you may specify no 
label processing (NL) in the FILEDEF command. When NL is specified, CBS 
does not open files on a tape containing a YCL1 label as its first 
record. You also can specify bypass tape label processing (BLP) on a 
FILEDEF command. BLP tells CMS to bypass tape label processing for a 
file, and instead, to position the tape at a particular file before 
processing the data records in the file. If you specify LABOFF for a 
FILEDEF tape file, label processing is turned off and there is no tape 
positioning or label checking- 

LABOFF is the default, so you do not receive any processing or tape 
positioning for a tape file unless you specifically request it. If you 
specify BLP, NL, SL, or SUL processing but omit a positional parameter, 
the position defaults to 1 and the tape is positioned at the first file. 
Examples of NL, BLP, and LABOFF processing are given in the sections "Ho 
Label (NL) Processing", "Bypass Label (BLP) Processing"^ and "Label Off 
(LABOFF) Processing". 
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JM Standard Tajoe Label Processina 

For IBM standard labels, you specify, SL or SDL, and optional positional 
and VOLID parameters. On a FILEDEF command, SUL means standard user 
labels. Everything you do for SL files, you must also do for SDL files. 
The positional parameter for standard label files works the same way it 
does in OS/VS. If you specify: 

filedef filex tapl si 2 

the tape is spaced to what is physically the fourth file on the tape 
before processing begins. The reason for this spacing is that a 
standard labelled tape has one header file, one data file, and one 
trailer file for each data file. If you leave off the positional 
parameter: 

filedef filey tapS sul 

you get the first file on the tape. 

The optional VOLID parameter on the FILEDEF command allows you to 
specify the volume serial number in the Y0L1 label of a tape in case you 
want only the V0L1 label checked on the tape. If you want to specify 
other fields in IBM standard labels, you must also provide a LABELDIF 
statement for the tape file. The LABELDEF statement allows you to 
assign values to all fields in a standard HERl or E0F1 label. A 
complete description of how the LABELDEF command works may be found in 
the "LABELDEF Command" section later in this publication. 

The followihg command defines filez as a standard labelled tape file 
on a tape with a V0L1 label and a volume serial number of DEPT78: 

filedef filez tap1 si volid dept78 

If you also wish to specify a data set identifier for filez, you must 
furnish a LABELDEF command for filez as well as the FILEDEF command. 
Data set name may not be specified on the FILEDEF command. The LABELDEF 
statement belcw assigns a data set name of payroll to filez. 

labeldef filez fid payroll 

You can also specify file sequence number, volume sequence number, 
expiration date and other fields on a LABELDEF command. However, if you 
are using OS simulation macros (OPEN, CLOSE, READ, WRITE,, GET, POT, 
etc.) to process your tape file, the only LABELDEF parameter that has 
meaning for input files is fid (data set identifier) . This is the only 
field that is checked on input by OS simulation. The other LABELDEF 
fields are used to specify values to be written in output labels. They 
are also used by other types of tape label processing (CMS/DOS and CMS) 
to check input labels. If no LABELDEF command has been supplied for 
output files, default values are used to write out labels (see the 
section on the LABELDEF command for the default values) . 

After you have set up your descriptive information for a standard 
labelled tape file in FILEDEF and LABELDEF statements, you run a regular 
OS simulation program under CMS. During program execution, HDR1 and 
HDR2 labels are written or checked at OPEN time. E0F1 and E0F2 labels 
are written or checked at CLOSE time. To have EOF labels processed, you 
must issue a CLOSE macro. The V0L1 label on a tape is checked whenever 
a file on that tape is opened if the user has specified a VOLID 
parameter on his FILEDEF statement or LABELDEF statement for the file. 
If the volid is specified on both LABELDEF and FILEDEF, the more recent 
specification is used. If no volid is specified, it is not checked. 
After checking the volid, the tape is positioned and the HDR label is 
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processed. For processing multifile volumes, you may wish to use the 
LEAVE option on the FILEDEF command. This option prevents a tape from 
being rewound and positioned before each tape file is processed. The 
LEAVE option does not exist on an OS DD statement. 

For input files, HDR2 and E0F2 labels are skipped. There is no merge 
of information from a HDR2 label with information in the DCB as there is 
under an OS/VS operating system. Output HDR2/E0F2 records are written 
from information in the DCB and the CMSCB (FCBSECT) . Note that the tape 
density and TRTCH fields in HDR2/E0F2 records are taken from what the 
user specifies in his FILEDEF command for the tape file. They may net 
correspond to the actual density and TRTCH fields used to write the 
tape. 

TO process standard user labels in OS simulation, you must do the 
following: 

1. Specify the file as SDL in a FILEDEF command. 

2. Provide a routine to process the user standard labels in your 
program. 

3- Put the address of the user label routine in the DCB EXIT list of 
the DCB for the file. See the IBM publication 0S/VS1 Data 
llafl§3®l®£t Services Guide or OS/VS 2 MVS Data Management Services 
Guide, for instructions on how to establish a DCB EXIT list, and 
the exact linkage for communication between user label routines and 
the operating system. This exact linkage should be used under CMS 
with the following exceptions: 

a. There is no support for code x'06« EOV EXIT routine. 

b. For input labels, return codes 8 and 12 from the user routine 
are not supported. If an input return code is not 0, it is 
treated as if it were U. 

4. Note that your standard user label routines do not perform any 
input/output. They set up an output label for writing, but the CHS 
tape label processing routines actually write out the label. For 
input, the CMS label processing routines read in your user standard 
label but then give control to your routine to check the label. 



Mo Label (NL) Processing 

You should specify NL in the FILEDEF command when you expect a tape does 
not contain any IBM standard tape labels. CMS reads your tape at the 
time a file is opened and does not open the file if the tape contains a 
V0L1 label as its first record. If the tape does not contain a V0L1 
label, a file is opened and the tape is positioned by using the position 
parameter (n) . For example, if you specify: 

filedef fileg tapl n1 2 

fileg is not opened if the tape on tapl (181) has a V0L1 label. If the 
tape does not have a VOLl label, fileg is opened and the tape is 
positioned at the second file. If you do not specify a position 
parameter, the tape is positioned at the first file, (that is, the load 
point). 
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Bypass Label (BLP) Processing 

You should specify BLP in the FILEDEF coBmand to bypass tape label 
processing- CMS does not check your tape for an IBM standard tape 
label. It uses the position parameter you specified to position the 
tape during open processing. If you do not specify a position 
parameter, the default is 1. For example: 

filedef fileabc tape1 blp 4 

positions the tape at the fourth file when it opens fileabc. Because 
CMS does not know whether files on the tape are label files or data 
files, the tape is positioned at what is physically the fourth file, 
regardless of file content. Any label files on the tape are included in 
counting files. 

Label Off (L&BOFF) Processina 

You should specify LABOFF in the FILEDEF command if you want no 
positioning or label processing to occur during open processing. The 
position parameter is not valid for LABOFF. If you specify LABOFF, and 
your tape is positioned at record. 6 in the third file before you issue 
an OPEN macro, the tape is positioned at exactly the same record after 
open processing (record 6 in the third file) . The following FILEDEF 
command does not move tape2 (182) before processing the data in fileb: 

filedef fileb tap2 laboff 



Nonstandard Label (NSJi) P£2£6ssin£ 

In order to process nonstandard labels, you must write your own routine 
to read, write, and check the labels. If you have such a routine as a 
CMS TEXT or MODULE file, you put the filename of the routine after the 
NSL keyword parameter in the FILEDEF command for the file. The filename 
must be the name of the first CSECT in the program. It is to this point 
that control is transferred when the NSL routine gets control. If you 
do not have a TEXT or MODULE file with the NSL filename you specify, you 
get an error message. The OPEN and CLOSE routines will load your module 
if it is not already in storage and will pass control to it at the time 
they are opening or closing the file. Your routines will then be 
responsible for processing the tape labels. Nonstandard label routines 
must do the actual reading and writing of tape labels as well as 
checking and setting up the label. This is one of several ways 
nonstandard label processing is different from standard user label 
processing. Because the CMS label processing routines do not know the 
size or format of your nonstandard labels, they cannot read or write the 
labels. 

If you use a MODULE file for an NSL routine, it is important that you 
create the MODULE file so that it starts at an address that will not 
allow it to overlay the program or command you are executing at the time 
the NSL routine is invoked. The reason for this restriction is that the 
NSL routine is dynamically loaded while your program is executing- For 
the TAPEMAC and TAPPDS commands, starting the NSL routine at an address 
above X»21000« prevents such an overlay. If the NSL routine is invoked 
from your own program which is running in the user area, you must 
determine how big your program is and where the NSL MODULE file should 
be located to prevent overlay. Note that you do not have to specify a 
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starting address for NSL routines that are TEXT files. The CMS loader 
loads such files for you at an address that does not cause an overlay. 

Although any user may write his own NSL routine, it is expected that 
a system programmer will usually write such routines and then other 
programmers in the installation will use them. Before writing an NSL 
routine, read the Introduction to CMS, Interrupt Handling, and CBS 
Functional Information sections in Part 3 of the VM/370 System 
i.E29iL^EE^E^ Guide. In order to ensure proper communication with the CHS 
system routines, you must use the linkage described below when you write 
nonstandard label routines. 

When an NSL tape label processing routine gets control, register 1 
points to a 16-byte parameter list with the following format: 



byte 

byte 4 
byte 8 
byte 12 



Reserved 



Type I Caller | Tape Mode— | 
call I id I Set Byte | 

TAPID 

FCBSECT address 



DCB address 



-1 ID parameter 

I for 

I TAPEMAC and 

I TAPPDS 



The Type call 
being done: 

x«00» 
x»04' 
x»08' 
x»OC« 
xMO* 



field is a code telling the type of label processing 



is OPEN input 

is OPEN output 

is CLOSE input 

is CLOSE output 

is End of Tape output 



The Caller id is a one-byte code which is one of the following: 

x»80« Call by OS simulation 

x»20« Call by CMS TAPEMAC or TAPPDS commands 

Tape modeset byte is used to communicate with the CMS tape I/O 
routines. It is a one byte hexadecimal code that depends on the type of 
tape (7 or 9 track) , tape density, etc. For further information on the 
Mode Set, see the TAPE command description in the VM/370 CMS Command 
and Macro Reference. (You probably will pass this byte to the CMS tape 
controlling module to read and write your tape labels and will never 
need to know what its codes mean.) 



FCBSECT address is the address of 
file you are processing. 



the CMSCB (FCBSECT) for the tape 



DCB address 
processing. 



is the address of the DCB for the tape file you are 



Note that for the TAPEMAC and TAPPDS commands, the same interface is 
used, except that instead of the FCBSECT and ECB address fields, the 
eight character identifier specified in the ID=identif ier field in the 
command is passed. This identifier enables you to identify which file 
you are processing since the TAPEMAC and TAPPES commailds do not work 
with CMSCBs or DCBs. 
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Control is passed to your NSL routine by a BALE 14,15 instruction so 
register 15 contains the address of your routine when you receive 
control. Register 1U contains the address you should return to when you 
are finished processing the nonstandard labels. You can return with a 
BR 14 instruction. When you receive control, register 13 points to a 
save area in which to store the callers register. The save area linkage 
is standard OS/VS linkage. You receive control with a PSW key of X'E* 
which allows you to modify only user storage. When you are finished 
processing, place a code in register 15 to the CMS label processing 
routine that called your routine. Place the value (zero) in register 
15 if there have been no errors and you want processing to continue 
normally and the data set to be opened. If you return a nonzero value 
in register 15, a message is issued to your terminal and the data set is 
not opened. 

If you write the following FILEDEF statement: 

filedef tapfl tapl nsl readlab 

and have a program called READLAB as a MODULE or TEXT file, your program 
will receive control when the data set called tapfl is opened. When 
your program gets control, register 1 contains the address of the 
parameter list described above. Using the data in this parameter list, 
you are able to read or write your own tape header labels. When the 
same data set is closed, your program again receives control and you can 
read or write your own trailer labels. Your program can test whether it 
is getting control for OPEN or CLOSE by examining the type call byte in 
the parameter list passed to you. If the type call byte is xMO', your 
NSL routine is being invoked while you are writing an output data set 
and you have reached the reflective mark that indicates end of tape. 
You may wish to do special processing in this case. See the "End of 
Tape" and "End of Volume" section in this publication for further 
information on end of tape processing. 



differences Between Ta£e Label Processing Onder OS/VS and OS Simulation 
in CMS 

There are a few minor differences in the way CMS OS simulation processes 
tapes and the way OS/VS processes them. These differences are listed 
below. 

• If you are using OS/VS and you do not specify any label parameter on 
your JCL statement, the default is SL or standard labels. When you 
use OS simulation under CMS and do not specify any label information 
on a FILEDEF statement, the default is LAEOFF. LABOFF turns off 
label processing and nothing is done to position the tape or process 
labels. Thus, if you specify no label information on FILEDEF, the 
system will process your tape files exactly the same way they are 
processed on a CMS system that has no tape label processing 
facilities. 

• You must specify CLOSE to process all trailer labels. No automatic 
CLOSE occurs at end of data or after reading a tape mark. There is 
no EOV monitor to process labels before a data set is closed. If an 
input tape is positioned at an E0F1 or E0V1 record when CLOSE is 
issued, the label is processed. If a tape file is closed before all 
data records are read, the trailer label is not processed. Output 
tapes have EOF records written only at CLOSE time. 

• There is no deferred label processing under OS simulation in CMS. 
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• When the user has not specified a block count routine in his DCB EXIT 
list under OS/VS, the program abends when a block count error occurs. 
Under CHS, this condition produces a message that asks whether or not 
to abend the operation. 

• Certain fields in HDR1 and E0F1 labels default to values different 
from those under OS/VS. These values can always be specified in a 
LABELDEF command if the user does not like the default values. For 
example, the default for data set name in an output label under OS 
simulation is DDNAME and not DSNAME. The default data set sequence 
number is always one even when the data set is not the first data set 
on the tape. The default volume sequence number is always one. Bead 
the section on the LABELDEF command in this manual to learn what the 
default values are under CMS. You can find what default values are 
in OS/VS by reading the IBM publication OS/VS Tape Labels. Note that 
you can always get exactly what you want written on a tape label by 
explicitly specifying the field on a LABELDEF command. For example^ 
you can specify DSNAME as FID on such a command and have it written 
in the label instead of DDNAME. 

• Default volids (when you do not specify a volid in a LABELDEF or 
FILEDEF statement) in output HDR1 and E0F1 records under CMS will be 
CMS001 and will not be the actual volume serial in the V0L1 record 
already en the tape. It is recommended that you always specify the 
volid in FILEDEF or LABELDEF to be sure the information written is 
correct. 

• Expiration date specification is always done in absolute form rather 
than by retention period. You must always use the form yyddd where 
yy is the year (0-99) and ddd the day (0-366) . CMS does not handle 
expiration dates specified by retention periods. 

• When CMS reads a HDR1 label and finds an unexpired file, it always 
issues a message allowing you to enter 'IGNORE' or 'ERROR'. 'ERROR' 
prevents opening the file but 'IGNORE' lets you ignore the error and 
write over the unexpired file. 

• The NSL routine linkage is quite diifferent under CMS than in OS/VS. 

(See the section "NSL Processing" for details.) 

• Volume serial number verification occurs every time a file on a tape 
is opened under OS simulation unless the FILEDEF LEAVE option is used 
for multifile tapes- 

• Existing VOLl labels are not automatically rewritten for density 
incompatibility in CMS as they are in OS/VS. 

• HDR2 records are skipped for input under CMS for OS simulation. They 
are not checked and information in them is not merged with DCB 
information. HDR2 records are written (with information obtained 
from the DCB) on output. 

• Blank tapes used for output in CMS cause the tape to run off the reel 
if you define the tape file as SL or NL. The tape label processing 
routines try to read an existing V0L1 or HDR1 label before writing on 
the tape. Therefore, you should always use the CMS TAPE command to 
write at least one tape mark (for NL tapes) or a V0L1 label (for SL 
or SUL tapes) before using the tape to write an output data set. 

• If you specify a position parameter that is too big (that is, there 
are not that many files on the tape), the tape will run off the reel 
in CMS. 
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• There are no user exits for user standard labels for EOV label 
processing in CMS. 

• CMS does not support user return codes of 8 and 12 for input standard 
user labels. If the return code from a user routine is not zero 
after input label processing, CMS treats it as if the return code was 
4. (See the IBM publication QS/VSl. Data Management Services Guide or 
0S^VS2 MVS Data Management Services Guide for details) . 

• No count is kept of user standard labels read or bypassed in CMS,. If 
more than eight such labels exist, the fact is not detected. 

• User label processing routines do not receive control under CMS when 
an abend or a permanent I/O error occurs. 

• If a CMS output tape is not positioned at a HDR1 label or a tape mark 
when label processing begins, error message 422 is issued. Under 
OS/YS such conditions cause an abend. 

• TCLOSE with the REREAD option causes a tape to be rewound under CMS 
and then forward spaced one file if the tape has standard labels. 
Under OS/VS, the tape is backspaced four files and forward spaced one 
file. REREAD for unlabelled tapes in CMS always causes a rewind. 

For further information on OS/VS tape label processing, refer to the 
following IBM publications: 0S/VS1 Data Management Services Guide, 
QS/VS2 MVS Data Management Services Guide, 
and QS/VS Ta£^ Labels. 

For details on end-of-tape/end-of-volume processing under CMS, see 
the "End-of-Volume" and "End-of-Tape Processing" section later in this 
publication. 



LABEL PROCESSING IN CMS/DOS 

You specify the type of label processing you want in CMS/DOS on a DTFMT 
macro in exactly the same way you specify it when you want to run your 
I program under DOS/VSE. See the VM/370 System Proarammer_^s Guide for 
details on CMS support for the DTFMT macro. 

Labelled tapes are only supported if you use the DTFMT macro. There 
is no support for labelled tapes in , CMS/DOS for any other type. If you 
try to read labelled tapes with a DTFCP or DTFDI macro, input standard 
IBM header labels are skipped, but no other input labels are processed. 
Output tapes with standard labels have these labels overwritten with a 
tape mark. All tape work files are treated as output unlabelled files 
in CMS/DOS although they are defined by a DTFMT. Tapes used for such 
files have a tape mark written as the first record when the file is 
opened. 

Unlabelled and Nonstandard Labelled Ta£es 

You define an unlabelled tape with the DTFMT parameter FILABL=NO. The 
tape file is processed as having no labels. 

You define a nonstandard labelled tape with the DTFMT parameter 
FILABL=NSTD- YOU also must provide a routine to process your 
nonstandard labels in the LABADDR=parameter of the DTFMT. Tape 
I processing in CMS for these files is the same as it is under DOS/VSE. 
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standard Labelled Ta^es 

You define a standard label tape with the DTFMT parameter FILABL=STC. 
YOU also must supply a LABELDEF command to specify label description 
information. This command replaces the DOS/VSE TLBL card and is 
required for standard label processing under CMS/DOS. The LABELDEF 
command is discussed in detail in the "LABELDEF Command" section later 
in this publication. 

In order to connect the LABELDEF command for a file with the DTFMT 
for the same file, you must use the same name to label your DTFMT as you 
use for a filename in your LABELDEF command. If you code a DTFMT macro 
in your program as: 

MT1 DTFMT . . .FILABL=STD 

you must then supply the following type of LABELDEF command: 

labeldef mtl fid yourfile fseg... 

You can put any description parameters you want on your LABELDEF 
command but the filename for it must be mt1 if you coded MT1 as the 
label on the DTFMT- 

After you have set up your DTFMT and LABELDEF, you execute your 
CMS/DOS program. HDRl labels are checked or written when an OPEN macro 
is issued. E0F1 labels are checked or written when a CLOSE macro is 
issued. A V0L1 label volume serial number is checked only if the tape 
is positioned at load point when the label processing begins and if you 
have specified a VOLID parameter on a LABELDEF statement for the file. 
Note, if NOREWIND is not specified in the DTFMT macro for the file^ the 
tape is rewound so it is positioned at load point for label processing. 

If you want to process user standard labels as well as standard 
labels in CMS/DOS, you specify FILABL=STD and also supply a LABADER 
parameter in the DTFMT for the file. Control is then transferred to 
your label processing routines after standard labels are processed. The 
linkage to user standard label routines is exactly the same as in 
DOS/VSE. 



Differences Between Tape Label Processing Under DOS/VSE and CMS/DOS 

There are minor differences in the way tapes are processed by CMS/DOS 
and the way they are processed by DOS/VSE. These differences are: 

• The tape error messages are CMS error messages and not DOS/VSE error 
messages. In some cases DOS/VSE allows the system operator to reply 
NEWTAP to an error message. The system then waits for the operator 
to mount a new tape and continues processing with this new tape. 
Such a reply is never possible under CMS/DOS. In CMS/DOS, you 
usually can reply IGNORE to ignore a tape label error condition or 
CANCEL to cancel a job. NEWTAP is never allowed. In a few cases, 
CMS/DOS allows an IGNORE reply where DOS/VSE does not. 

• You must specify CLOSE to process all trailer labels. No automatic 
CLOSE occurs at end of data or after reading a tape mark. If an 
input tape is positioned at an E0F1 or E0V1 record when CLOSE is 
issued, the label is processed. If a tape file is closed before all 
data records are read, the trailer label is not processed. Output 
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tapes have EOF records written only at CLOSE time. For nonstandard 
labelled tapes, your own routines do not receive control on input 
when a tape mark is read. You must issue a CLOSE macro in your 
EOFADDR routine in order to have the trailer labels processed. 

► Certain fields in HDR1 and E0F1 labels default to values different 
from those in DOS/VSE. For example, the default volume serial number 
written in a HDRl label is CMS001 and not the actual volume serial 
number (volid) in the V0L1 label already on the tape. The default 
file sequence and volume sequence numbers are always one even when 
the file is not the first file on the tape. You should read the 
section on the LABELDEF command in this publication to learn what the 
default values are in CMS/DOS. You also can read the IBM publication 
POS^ISE Ta^e Labels to find what the default values are for DOS/VSE. 
If you do not like the default values, you can always specify the 
exact values you want in label fields in a LAEELDEF command. 

' Expiration date specification is always done in absolute form rather 
than by retention period. You must always use the form yyddd where 
yy is the year (0-99) and the ddd the day (0-366). CMS does not 
handle expiration dates specified by retention periods. 

I V0L1 labels written in the wrong density are not rewritten 
automatically by CMS/DOS as they are by DOS/VSE. 

' Blank tapes should not be used for tape files specified as FILABL=STD 
in CMS/DOS; they will run off the reel. Use the CMS TAPE command to 
write a V0L1 label or a tape mark on a blank tape before using it for 
a STD file. 

Not all tape movement and label checking that occurs in DOS/VSE 
occurs under CMS. For example, when opening an output file, a 
DOS/VSE system expects the tape to be positioned at a HDRl label or a 
tape mark. It then backspaces the tape to read the last E0F1 label 
on the tape. If it does not find the label it expects, it issues an 
error message. This check is not performed by CMS/DOS. If the tape 
is not positioned at a HDR1 label or a tape mark when output open 
processing begins, error message U22 is issued. 

After an EOVl label is written (see "End-of-Tape/End-of-Volume 
Processing" later in this publication) , the tape is always rewound 
and unloaded under CMS/DOS. DOS/VSE lets a DTFMT parameter control 
whether or not the tape is rewound. 

User label processing routines do not receive control when an I/O 
error occurs under CMS/DOS. 

Control is not passed to user standard label routines in CMS/DOS when 
EOT has been sensed on output and an EOVl label has been written by 
the system routines. 

Work tapes are not checked for an expiration date when they contain 
standard labels under CMS/DOS. If a tape is to be opened as a work 
tape, CMS/DOS tests to see if it contains a V0L1 label. If it does, 
a dummy HDRl label and a tape mark are immediately written on the 
tape after the V0L1 label. If the tape does not contain a VOLl 
label, a tape mark is written at the beginning of the tape. DOS/VSE 
checks expiration dates on previously labelled tapes used as work 
tapes and gives the operator a chance to reject the tapes if the 
expiration date has not expired. 
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I For further information on DOS/VSE and CMS/BOS tape label processing, 
refer to the following IBM publications: 

I DOS/VSE Tape Labels 

I DOS/VSE Macro User's Guide 

I DOS/VSE LIOCS Vol 2 



CMS TAPESL MACRO 

The TAPESL macro is provided for use in CMS programs that do not use OS 
and DOS simulation features. You can use the CMS TAPESL macro to 
process IBM standard HDR1 and E0F1 labels without using DOS or OS OPEIJ 
and CLOSE macros. You will probably lise TAPESL with the RDTAPE, WRTAPE, 
and TAPECTL macros. 

TAPESL processes only HDRl and E0F1 labels. It does not perform any 
functions of opening a tape file other than label checking or writing. 
The TAPESL macro generates linkage to the CMS tape label processing 
routine that actually processes the label. The macro generates a block 
of data (32 bytes long) in order to communicate with the tape label 
processing routines. TAPESL is used both to check and to write tape 
labels. A LABELDEF command must be issued prior to running the program 
that contains this macro. The LABID parameter of the TAPESL macro is 
used to specify the name of the LABELDEF to be used. For example, if 
you use the macro: 

TAPESL HOOT, 181, LABID=GOODLAB 

in your assembly language program, you must supply a LABELDEF command 
for GOODLAB: 

labedef goodlab fid filelO fseg a exdte 78235 

The tape must be positioned correctly (at the label to be checked or at 
the place where the label is to be written) , before you issue the macro. 
TAPECTL may be used to position the tape. TAPESL reads or writes only 
one tape record unless you specify SPACE=YES for input. Then it spaces 
the tape to beyond the tape mark that ends the label file. TAPESL reads 
and checks a tape V0L1 label provided the tape is positioned at load 
point and the user has specified a volid in his LABELDEF command. 



TAPE LABEL PROCESSING BY CMS COMMANDS 

There are three types of CMS commands that do some type of tape label 
processing- They are: 

• TAPEMAC and TAPPDS commands 

• TAPE command 

• MOVEFILE command 



TAPEMAC and TAPPDS Commands 

TAPEMAC and TAPPDS have operands where you can indicate the type of 
label processing you want. The tape must be positioned properly (at the 
data file or label file you want) before you issue the command,. The 
TAPE command may be used for positioning. A separate LABELDEF command 
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is required for these commands if IBM standard latel checking is 
desired. If SL label type is specified without a labdefid, standard 
header labels are displayed on the terminal but not checked lay the CMS 
label processing routines. The command: 

tapemac macfile SL (tap2 

displays any standard labels that exist on your terminal while the 
series of commands: 

labeldef maclab fid macro volseq 2 crdte 77102 

tapemac macfile si maclab (tap2 

invokes the CMS tape label processing routines. These routines check to 
see that your tape has a HDRl label that has a file identifier of macro, 
a volume sequence number 2, and a creation date of 77102. V0L1 labels 
are not checked during label processing by TAPEHftC and TAPPDS unless the 
tape is positioned at load point and you have specified a volid on your 
LABELDEF command. The DVOLl function of the TAPE command can be used 
for volume verification before positioning the tape if the user does not 
want to start at the first file. These commands process only HDR1 
labels; they skip HDR2, UHL, and all trailer labels without processing 
them. 

To process nonstandard tape labels with TAPEMAC and TAPPDS, you use 
the same interface described in the section "NSL Processing under OS 
Simulation." The only difference is that instead of putting the CMSCB 
and DCB addresses in the parameter list, the ID parameter you placed in 
the command line is passed to your NSL routine. 

tappds pdsfile cmsuti * nsl superck id XYZ123U5 

passes the EBCDIC identifier XYZ123U5 to your nonstandard label checking 
routine called SUPERCK. This identifier may be up to eight characters 
long and is left justified in bytes 8-15 of the parameter list. You can 
use the identifier to inform your NSL routine of what file you are 
processing- 

Ia£e Command DVOLJ and WVQIil Functions 

Use the DVOLl function of the CMSTAPE command to display the VOLl label 
of a tape on your terminal. You may use this command to ensure the 
system operator has mounted the correct tape before you begin processing 
the tape. If the tape does not have a VOLl label and you issue the 
CMSTAPE command, you are informed that the VOLl label is missing. Do 
not use TAPE DVOLl if you have a blank tape. If TAPE DVOLl is issued 
and a blank tape is used, CMS will search the entire tape to find the 
label record; since the tape is void of any records, the tape will run 
off the end of the reel. 

Use the WV0L1 function on the TAPE command to write a VOLl label on a 
tape. You can specify a one- to six-character volume serial number 
(volid) through this command and also a one- to eight-character owner 
field- 

MOVEFILE Command 

You can use the MOVEFILE command to move labelled tape files if these 
files are defined as labelled by the FILEDEF command. The MOVEFILE 
command supports only SL, NSL, BLP, NL, and LABOFF processing. SUL 
files are processed as SL files and no user exits are taken. 

Section 7. Using Real Printers, Punches, Readers, and Tapes 122.11 



Pg. of GC20- 1819-2 Rev March 30, 1979 by Supp. SD23-902U-1 for 57U8-XX8 

YOU can also use the MOVEFILE command to display tape labels on your 
terminal if you want to see what these labels look like. The following 
sequence displays the V0L1 and first HDa1 labels on tapU if the tape has 
standard labels: 

filedef in tap4 

filedef out term 

tape rew (tapU 

move in out 

LABELDEF COMMAND 

The LABELDEF command is used to specify the exact data you want written 
in certain fields of a HDRl or EOFI tape label for output. It can also 
be used to specify fields in the same labels that you want checked on 
input- If you do not explicitly specify a field for output, a default 
value is used. If you do not explicitly specify a field for input, the 
field is not checked. For example: 

labeldef abc fid master volseq 1 exdte 77364 

used for input tells CMS to check the file identifier volume sequence 
number and expiration date in an input HDR1 label. No other fields in 
the label are checked. The same specification used for output causes 
the HDR1 label to have MASTER written in the file identifier field, 1 
written in the volume sequence number field and 77364 written in the 
expiration date field. Default values are written in the HDR1 fields 
that are not specified. 

Default values for HDRl labels are as follows: 

FID - for OS simulation, the DDNAME (Specified on FILEDEF) 
for CMS/DOS, the DTFMT symbolic name 
- for CMS TAPESL macro, the LABELDEF id (LABID=labeldef id) 
parameter 



VOLID 


- CMS001 


VOLSEQ 


- 0001 


FSEQ 


- 0001 


GENN 


- blanks 


GENV 


- blanks 



CRDTE - current date that label is written 
EXDTE - current date that label is written 



SEC 







The filename on the LABELDEF command is used to connect your label 
definition to a file defined elsewhere. This is why you specify 
different data for file name depending on the type of tape label 
processing you are doing. Filename is DDNAME for OS simulation, DTFMT 
symbolic name for CMS/DOS and labeldef id for TAPESL. 



The LABELDEF 
for CMS/DOS. 



command takes the place of the DOS/VSE TLBL statement 
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END-OF-VOLUME AND END-OF-TAPE PROCESSING 

There is no true end-of-volume support available with CMS tape label 
processing. FEOV instructions are not supported under OS simulation and 
there is no automatic volume switching. Multivolume files are not 
supported. The following features exist to aid the IBM standard label 
tape user when he reaches end-of-tape on output or an EOV label in 
input. These are the only ways in which CMS supports EOV processing. 

• Input - When a CLOSE macro is issued or when a TAPES! macro processes 
an input trailer label, a message is issued if the label read is an 
E0V1 label instead of an E0F1 label. The E0V1 label is then 
processed exactly as if it were an E0F1 label. You must request that 
the operator mount a new tape and reopen a file if you want to 
continue processing the data. 

• Output - Under CMS/DOS and OS simulation processing only (that is, 
the processing does not occur for TAPESL or CMS commands), the 
following limited EOV processing occurs: 

a. If you specify that you have an IBM standard label tape file, a 
single tape mark is written to end your data. This occurs when 
end-of-tape is sensed on output while you are using regular access 
method macros to write the file. The tape mark is written 
immediately after the record that caused the EOT to be sensed. 
Following this tape mark, CMS writes an E0V1 label and a single tape 
mark. It then rewinds and unloads your tape. A message is issued 
telling you that an EOVl label was written. If you specified 
nonstandard labels instead of writing the EOVl label, an exit to the 
nonstandard label routine you specified for the file is taken after 
the end-of-data tape mark is written. For BLP or NL files, only the 
ending tape mark is written. 

b. CMS/DOS jobs are always canceled after an EOT condition is 
detected on output. In order to continue processing the tape, you 
must have a new tape mounted, run the same job over again or run a 
new job and reopen the file. 

c. OS simulation programs that use QSAM or contain a BSAM CHECK 
macro cause an abend when EOT is detected, with code 001 after an 
error message. A BSAM program that does not use a CHECK macro has no 
way of detecting the EOT condition. Such a program continues to try 
to write on the tape after it is rewound and unloaded. The program 
enters a wait state rather than continue running to a normal or 
abnormal completion. Therefore, you should always include a BSAM 
CHECK macro after the WRITE if you expect your program to reach 
end-of-tape. OS simulation users are also responsible for completing 
processing on a new tape with the same or a new job after an EOT is 
detected. 

d. If you are a CMS/DOS user you always get the automatic output 
end-of-tape processing described above. However, if you are an OS 
simulation user and do not want CMS to do any special end-of-tape 
processing, you can suppress it by using the NOEOV option on your 
FILEDEF command for the file. If you enter: 

filedef ddl tapS si (noeov 

no tape marks or EOVl labels are written when EOT is sensed on 
output- Your tape is not rewound and unloaded. However, the program 
causes an abend if you use QSAM or include a BSAM CHECK macro after 
your WRITE macro. Without a CHECK macro, a BSAM program runs the 
tape off the reel when EOT is sensed and NOEOV is specified. 
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ERROR PROCESSING 

When the standard label processing routines find errors or discrepancies 
on tape labels, they send a message to the CHS terminal user who is 
processing the tape. After an error message is issued, the user can ask 
the system operator to mount a new tape, use the CMS TAPE command to 
position the tape at a different file, or respecify his label 
description information. If you are a terminal user and want another 
tape mounted, you send the system operator a message telling him what 
tape to mount. 

Some errors cause program termination and others do not. The effect 
of tape label processing errors depends on both the type of error and 
the type of program (that is, CMS/DOS, OS simulation, CMS command, etc.) 
that invokes the label processing. The following are general guidelines 
on error handling: 

• Messages identifying the error are always issued. 

• Onder OS simulation, tape label errors result in open errors. These 
errors prevent a tape file from being opened. They do not 
necessarily end a job. Errors in trailer labels (except block count 
errors) have no effect on processing. 

• In CMS/DOS, the terminal user is generally given two choices: ignore 
the error or cancel the job. The new-tape option is not allowed. 

• The CMS commands TAPEMAC and TAPPDS terminates with a non-zero return 
code after a tape label error. 

• Certain error situations such as unexpired files and block count 
errors for OS simulation allow the user to ignore the error and do 
not cause open errors. In these cases, the user enters his decision 
at the terminal after he is notified of the error. 

• Errors that occur during the loading of an NSL routine cause an abend 
(code 155 or 15A) . A block count abend gives an error code of 500. 

In all cases, after an error has been detected and diagnosed, you 
must decide what to do. You may wish to have a new tape mounted and 
then re-execute the command or you may want to respecify your LABELDEF 
description if it was incorrect. You can also use the TAPE command to 
space the tape to a new file if it was positioned incorrectly. 



THE MOVEFILE COMMAND 

The MOVEFILE command can copy sequential tape files into disk files, or 
sequential disk files onto tape. It can be particularly useful when you 
need to copy a file from a tape and you do not know the format of the 
tape. 

To use the MOVEFILE command, you must first define the input and 
output files using the FILEDEF command- For example, to copy a file from 
a tape attached to your virtual machine at virtual address 181 to a CMS 
disk, you would enter: 

filedef input tapl 

filedef output disk tape file a 

movefile input output 
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This sequence of coimands creates a file naied TAPE FILE A1. Then use 
CHS commands to manipulate and examine the contents of the file. 

MOVEFILE can also be used to display tape labels and/or ^move labelled 
tape files. See "Tape Labels in CMS" for details. 



TAPES CREATED BY OS UTILITY PROGRAMS 

The CMS command TAPPDS can read OS partitioned and sequential data sets 
from tapes created by the lEBPTPCH, lEBOPDTF, and lEHMOVE utility 
programs. When you use the TAPPDS command, the OS data set is copied 
into a CHS disk file, or in the case of partitioned data sets, into 
multiple disk files. 

lEBPTPCH: Sequential or partitioned data sets created by lEBPTPCH must 
be unblocked for CMS to read them. If you have a tape created by this 
utility, each member (if the data set is partitioned) is preceded with a 
Card that contains **MEH6ER=membername". If you read this tape with the 
command: 

tappds * 

then, CHS creates a disk file from each member, using the membername for 
the filename and assigning a filetype of CHSDT1. If you want to assign a 
particular filetype, for example TEST, you could enter the command as 
follows: 

tappds * test 

If the file you are reading is a sequential data set, you should use the 
) NOPDS option of the TAPPDS command: 

tappds test file (nopds 

The above command reads a sequential data set and assigns it a file 
identifier of TEST FILE. If you do not specify a filename or filetype, 
the default file identifier is TAPPDS CMSUT1. 

lEBUPDTE; Tapes in control file format created by the lEBDPDTE utility 
program'can be read by CHS. Data sets may be blocked or unblocked, and 
may be either sequential or partitioned. Since files created by 
lEBOPDTE contain ./ADD control cards to signal the addition of members 
to partitioned data sets, you must use the C0L1 option of the TAPPDS 
command. Also, you must indicate to CMS that the tape was created by 
lEBOPDTE. For example, to read a partitioned data set, you would enter 
the command: 

tappds * test (update coll 
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The CMS disk files created are always in unblocked, 80-character fornat. 

lEHMOYE; OS unloaded partitioned data sets on tapes created by the 
lEHMOVE utility program can be read either by the TAPPDS command or by 
the TAPEMAC command. The TAPPDS command creates an individual CMS file 
from each member of the PDS. 

If the PDS is a macro library, you can use the TAPEMAC command to 
copy it into a CMS MACLIB. A MACLIB, a CMS macro library, has a special 
format and can usually be created only by using the CMS MACLIB command. 
If you use the TAPPDS command, you have to use the MACLIB command to 
create the macro library from individual files containing macro 
definitions. 



SPECIFYING SPECIAL TAPE HANDLING OPTIONS 

Tor most of the tape handling that you do in CMS, you do not have to be 
concerned with the density or recording format of the magnetic tapes 
that you use. There are, however, some instances when it may be 
important and there are command options that you can use with the TAPE 
command MODESET operand and with ASSGN and FILEDEF command options. 

The specific situations and the command options you should use are 
listed below. 

• If you are reading or writing a 7-track tape and the density of the 
tape is either 200 or 556 bpi, you must specify DEN 200 or DEN 556. 

• If you are reading or writing a 7-track tape with a density of 800 
bpi, you must specify 7TRACK. 

• If you are reading or writing a 7-track tape without using the data 
convert feature, you must use the TRTCH option. 

• If you are writing a tape using a 9-track dual density tape drive 
with the 9TRACK option specified, and you want the density to be 800 
(on an 800/1600 drive) or 6250 (on a 1600/6250 drive), then you must 

specify DEN 800 or DEN 6250. 

• If you are writing a tape, the default tape block size is U096 bytes 
plus a 5-byte header. This format is not compatible with previous 
VM/370 systems. Therefore, if you want to write a tape compatible 
with previous VM/370 systems, you must use the 'BLK 800* option of 
the TAPE command. The TAPE command is described in detail in VM^370 
CMS Command and Macro Reference. 

Using the Remote Spooling Communications 
Subsystem (RSCS) 

If your VM/370 installation is on a Remote Spooling Communications 
Subsystem (RSCS) network, you can send printer, punch, or reader spool 
files to users at remote locations. To send a spool file, you must know 
the userid of the virtual machine at your location that is running RSCS 
and the location identification (locid) of the remote location. If you 
are sending a spool file to a particular user at the remote location, 
you should also know that userid of the user. 

. The CP commands that you can use to transmit files across the network 

I are TAG and SPOOL. The TAG command allows you to specify the locid and 
^ userid that are to receive a spool file, or, in the case of tagging a 
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printer or punch, of any spool files produced by that device. With the 
SPOOL command, you spool your virtual device to the RSCS virtual 
oachine. You can also use the TRANSFER command to transfer files from 
your own virtual card reader. 

The CP commands TAG, SPOOL, and TRANSFER are discussed in detail in 
the publication YM/370 CP Command Reference for General Users. 
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Part 2. Program Development Using CMS 

You can use CMS to write, develop, update, and test: 

• OS programs to execute either in the CHS environment (using OS 
simulation) or in an OS virtual machine 

• DOS programs to execute in either the CMS/DOS environment or in a DOS 
virtual machine 

• CMS programs to execute in the CMS environment 

The OS and DOS simulation capabilities of CHS allow you to develop OS 

and DOS programs interactively in a time-sharing environment. When your 

programs are thoroughly tested, you can execute them in an OS or DCS 
virtual machine under the control of VM/370. 

"Section 8. Developing OS Programs Under CHS" is for programmers who 
use OS. It describes procedures and technigues for using CHS commands 
that simulate OS functions. 

"Section 9. Developing DOS Programs Under CHS" is for programmers who 
use DOS. It describes procedures and technigues for using CHS/DOS 
I commands to simulate DOS/VSE functions. 

If you use VSAM and access method services in either a DOS or an OS 
environment, "Section 10. Using Access Method Services and VSAM in CMS 
and CMS/DOS" provides usage information for you. It describes how to 
use CMS to manipulate VSAM disks and data sets. 

You can use the interactive facilities of CP and CMS to test and 
debug programs directly at your terminal. "Section 11- How VH/370 Can 
Help You Debug Your Programs" shows examples of commands and debugging 
techniques. 

The CMS batch facility is a CMS feature that allows you to send jobs 

to another machine for execution. How to prepare and send job streams 

to a CMS batch virtual machine is described in "Section 12. Using the 
CMS Batch Facility." 

As you learn to use CMS, you may want to write programs for CMS 
applications. "Section 13. Programming for the CHS Environment" 
contains information for assembler language programmers: linkage 
conventions, programming notes, and macro instructions you can use in 
CMS programs. 
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Section 8. Developing OS Programs under 
CMS 



CMS simulates many of the functions of the Operating System (OS) , 
allowing you to compile, execute and debug OS programs interactively. 
For the most part, you do not need to be concerned with the CMS OS 
simulation routines; they are built into the CMS system. Before you can 
compile and execute OS programs in CMS, however, you must be acquainted 
with the following: 

• OS macros that CMS can simulate 

• Using OS data sets in CMS 

• How to use the FILEDEF command 

• Creating CMS files from OS data sets 

• Using CMS and OS macro libraries 

• Assembling programs in CMS 

• Executing programs 

These topics are discussed below. Additional information for OS VSAM 
users is in "Section 10. Using Access Method Services and VSAM Under CMS 
and CMS/DOS." 

For a practice terminal session using the commands and techniques 
presented in Section 8, see "Appendix D: Sample Terminal Sessions." 



A Note About Terminolog]^ 

The CMS system uses many OS terms, but there are a number of OS 
functions that CMS performs somewhat differently. To help you become 
familiar with the some of the CMS equivalents (where they do exist) for 
OS terms and functions, see Figure 11. It lists some commonly-used CS 
terms and discusses how CMS handles the functions they imply. 
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OS Tera/Function 



Cataloged procedure 



Data set 



Data Definition (DD) 
card 



Data Set Control 
Block (DSCB) 

EXEC card 



Job Control Language 
(JCL) 

Link-editing 



Load lodule 



Object BOdule 



Partitioned data set 



STEPCAT,JOBCAT 



STEPLIB, JOBLIB 



Utility program 



Volume Table of 
Contents (VTOC) 



CMS Equivalent 



EXEC files can execute command sequences 
similar to cataloged procedures, and provide 
for conditional execution based on return 
codes from previous steps. 

Data sets are called files in CMS; CMS files 
are always sequential but CMS simulates OS 
partitioned data sets. CMS reads and writes 
VSAM data sets. 

The FILEDEF command allows you to perform the 
functions of the DD statement to specify 
device types and output file dispositions. 

Information about a CMS disk file is contained 
in a file status table (FST) . 

To execute a program in CMS you specify only 
the name of the program if it is an EXEC, 
MODULE file, or CMS command. To execute TEXT 
files, use the LOAD and START commands. 

CMS and user— written commands perform the 
functions of JCL. 

The CMS LOAD command loads object decks (TEXT 
files) into virtual storage, and resolves 
external references; the GENMOD command 
creates absolute nonrelocatable modules. 

CMS MODULE files (resulting from the LOAD and 
GENMOD commands) are nonrelocatable. 

Language compiler output is placed in CMS 
files with a filetype of TEXT. 

CMS MACLIBs and TXTLIBs are the only CMS files 
that resemble partitioned data sets. 

VSAM catalogs can be assigned for jobs or job 
steps in CMS by using the special ddnames 
IJSYSCT and IJSYSUC when identifying catalogs. 

The GLOBAL command establishes macro and text 
libraries; you can indirectly provide job 
libraries by accessing and releasing CMS disks 
that contain the files and programs you need. 

Functions similar to those performed by the OS 
utility programs are provided by CMS commands. 

The list of files on a CMS disk is contained 
in a file directory for 800-byte format CMS 
disks, or in the file directory for CMS disks 
with a 1024-, 2048-, or 4096-byte block format 



Figure 11. OS Terms and CMS Equivalents 
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Using OS Data Sets in CMS 



YOU can have OS disks defined in your virtual machine configuration; 
they may be either entire disks or minidisks: their size and extent 
depends on their VM/370 directory entries. You can use partitioned and 
sequential data sets on OS disks in CMS. If you want, you can create 
CMS files from your OS data sets. If you have data sets on OS disks, 
you can read them from programs you execute in CMS, but you cannot 
update them. The CMS commands that recognize OS data sets on OS disks 
are listed in Figure 12. 



) 



Command 
ACCESS 

ASSEMBLE 

CDR 

DLBL 

FILEDEF 



operation 



Makes the OS disk containing the data set available 
to your CMS virtual machine. 

Assembles an OS source program under CHS. 

Copies an entire OS disk to tape. 

Defines OS data sets for use with access method services 
and VSAM files for program input/output. 

Defines the OS data set for use under CMS by associating 
an OS ddname with an OS data set name. Once defined, 
the data set can be used by an OS program running under 
CMS and can be manipulated by the other commands that 
support OS functions. 

GLOBAL I Makes macro libraries available to the assembler. You can 
prepare an OS macro library for reference by the GLOBAL 
command by issuing a FILEDEF command for the data set and 
giving the data set a filetype of MACLIB. 

LISTDS I Lists information describing OS data sets residing on 
OS disks. 

MOVEFILE I Moves data records from one device to another device. Each 
device is specified by a ddname, which must have been 
defined via FILEDEF. You can use the MOVEFILE command to 
create CMS files from OS data sets. 

QOERY I Lists (1) the files that have been defined with the 

FILEDEF and DLBL commands (QOERY FILEDEF, QUERY DLBL) , or 
(2) the status of OS disks attached to your virtual machine 
(QUERY DISK, QUERY SEARCH) . 

RELEASE I Releases an OS disk you have accessed (via ACCESS) from 
your CMS virtual machine. 

STATE I Verifies the existence of an OS data set on a disk. 

Before STATE can verify the existence of the data set, 
you must have defined it (via FILEDEF) . 

I ^ : \ ^ '. 

Figure 12. CMS Commands That Recognize OS Data Sets and OS Disks 
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ACCESS METHODS SOPPORTED BY CMS 



OS access methods are supported, to varying extents, by CMS. Dnder CMS, 
you can execute programs that use the OS data management macros that are 
supplied for the access methods listed below. 



1 




CMS Support for OS 


CMS Support for Real 






Simulated Data Sets 


OS Data Sets on OS 


1 Access 


Method 1 


on CMS Disks 




Disks 


1 BDAM 




Yes 


No 




1 BPAM 




Yes 


Yes 


(read only) 


1 BSAM 




Yes 


Yes 


(read only) 


1 QSAM 




Yes 


Yes 


(read only) 


1 VSAM 




No 


Yes 





C J 



BPAM, BSAM, and QSAM; You can execute programs in CMS that read records 
from OS data sets using the BPAM, BSAM, or QSAM access methods. You 
cannot, however, write or update OS data sets that reside on OS disks. 



BEAM: CMS can neither read nor write OS 
BDAM access method. 



data sets on OS disks using the 



VSAM Files; CMS can read and write VSAM files on OS disks. For 
information on using VSAM under CMS, see "Section 10. Using Access 
Method Services and VSAM Under CMS and CMS/DOS." 



OS Simulated Data Sets 



If you want to test programs in CMS that create or modify OS data sets, 
you can write "OS simulated data sets." These are CMS files that are 
maintained on CMS disks, but in OS format rather than in CMS format. 
Since they are CMS files, you can edit, rename, copy, or manipulate them 
just as you would any other CMS file. Since they are in OS-simulated 
format, files with variable-blocked records may contain block and record 
descriptor words so that the access methods can manipulate them 
properly. 

The files that you create from OS programs do not necessarily have to 
be OS simulated data sets. You can create CMS files. The format of an 
output file depends on how you specify the filemode number when you 
issue the FILEDEF command to identify the file to CMS. If you specify 
the filemode number as 4, CMS creates a file that is in OS simulated 
data set format on a CMS disk. 



CMS can read and write OS simulated data sets using 
BSAM, and QSAM access methods. 



the BDAM, BPAM, 



When an input or output error occurs, do not depend on OS sense 
bytes. An error code is supplied by CMS in the ECB in place of the 
sense bytes. These error codes differ for various types of devices and 
their meaning can be found in the IBM VM/370 System Messages, under DMS 
message 120S. 



0t 

I 
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Restrictions for Reading OS Data Sets 

The following restrictions apply when you read OS data sets froa OS 
disks under CMS: 

• Read-password-protected data sets are not read. 

• BDAM and ISAM data sets are not read. 

• Multivolume data sets are read as single-volume data sets. 
End-of-volume is treated as end-of-file and there is no end-of-volume 
switching. 

• Keys in data sets with keys are ignored; only the data is read. 

• User labels in user-labeled data sets are bypassed (except for user 
standard labels on tapes) . See "Tape Labels in CMS" for details. 

• Results may be unpredictable if two DCBs access the same data set at 
the same time. 



Using the FILEDEF Command 

whenever you execute an OS program under CMS that has input and/or 
output files, or you need to read an OS data set onto a CMS disk, you 
must first identify the files to CMS with the FILEDEF command. The 
FILEDEF command in CMS performs the same functions as the data 
definition (DD) card in OS job control language (JCL) : it describes the 
input and output files. 

When you enter the FILEDEF command, you specify: 

• The ddname 

• The device type 

• A file identification, if the device type is DISK 

• Type of label on your tape file, if tape label processing is 
specified 

• Options (if necessary) 

Some guidelines for entering these specifications follow. 

SPECIFYIWG THE DDNAME 

If the FILEDEF command is issued for a program input or output file, 
then the ddname must be the same as the ddname or file name specified 
for the file in the source program. For example, you have an assembler 
language source program that contains the line: 

IHFILE DCB DDNAME=INPOTDD,MACRF=GL,DSORG=PS,RECFB=F,LRECL=80 

For a particular execution of this program, you want to use as your 
input file a CMS file on your A-disk that is named MYINPOT FILE, then, 
you must issue a FILEDEF for this file before executing the program: 
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filedef inputdd disk myinput file al 



If the input file you want to use is on an OS disk accessed as your 
C-disk, and it has a data set name of PAYROLL. RECORDS. AUGUST, then your 
FILEDEF command might be: 

filedef inputdd c1 dsn payroll records august 



SPECIFYING THE DEVICE TYPE 

For input files, the device type you enter on the FILEDEF command 
indicates the device from which you want records read. It can be DISK, 
TERMINAL, READER (for input from real cards or virtual cards), or TAPn 
(for tape) . Using the above example, if your input file is to be read 
from your virtual card reader, the FILEDEF command might be as follows: 

filedef inputdd reader 

Or, if you were reading from a tape attached to your virtual machine at 
virtual address 181 (TAP1): 

filedef inputdd tapl 

For output files, the device you specify can be DISK, PRINTER, PUNCH, 
TAPn (tape) , or TERMINAL. 

If you do not want any real I/O performed during the execution of a 
program for a disk input or output file, you can specify the device type 
as DUMMY: 

filedef inputdd dummy 

ENTERING FILE IDENTIFICATIONS 

If you are using a CMS disk file for your input or output, you specify: 

filedef ddname disk filename filetype filemode 

Note that if * is used for the filemode of an output file, unpredictable 
results may occur. 

The filemode field is optional; if you do not specify it, your A-disk is 
assumed. If you want an output file to be constructed in OS simulated 
data set format, you must specify the filemode number as 4. For 
example, a program contains a DCB for an output file with a ddname of 
OUTPUTDD, and you are using it to create a CMS file named DAILY OUTPUT 
on your B-disk: 

filedef outputdd disk daily output bU 

If your input file is an OS data set on an OS disk, you can identify 
it in several ways: 

• If the data set name has only two qualifiers, for example 
HEALTH. RECORDS, you can specify: 

filedef inputdd disk health records b1 
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» If it has Bore than two qualifiers, you can use the DSH keyword and 
enter: 

filedef inputdd b1 dsn health records august 1974 

Or you can request a prompt for a complete data set naae: 

filedef inputdd b1 dsn ? 
ENTER DATA SET NANE: 
health. records. august. 1974 
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Note: When you enter a data set name using the DSN keyword, either 
with or without a request for prompting, you should omit the device 
type specification of DISK, unless you want to assign a CMS file 
identifier, as in the example below. 

• You can also relate an OS data set name to a CMS file identifier: 

filedef inputdd disk ossim file c1 dsn monthly records 

Then you can refer to the OS data set MONTHLY. RECORDS by using the 
CMS file identifier, OSSIM FILE: 

state ossim file c 

When you do not issue a FILEDEF command for a program input or output 
file, or if you enter only the ddname and device type on the FILEDEF 
command, such as: 

filedef oscar disk 

then CMS issues a default file definition, as follows: 

FILEDEF ddname DISK FILE ddname A1 

where ddname is the ddname you assigned in the DDNAME operand of the DCB 
macro in your program or on the FILEDEF command. For example, if you 
assign a ddname of OSCAR to an output file and do not issue a FILEDEF 
command before you execute the program, then the CMS file FILE OSCAR Al 
is created when you execute the program- 

SPECIFYING CMS TAPE LABEL PROCESSING 

You can use the label operands on the FILEDEF command to indicate that 
CMS tape label processing is not desired (this is the default) . If CMS 
tape label processing is desired you can use the label operands on the 
FILEDEF command to indicate the types of labels on your tape. See "Tape 
Labels in CMS" for a description of CMS tape label processing. 



SPECIFYING OPTIONS 

The FILEDEF command has many options; those mentioned below are a 
sampling only. For complete descriptions of all the options of the 
FILEDEF command, see the VM/370 CMS Command and Macro Reference. 

BIjOCK, LRECL, RECFM, DSORG: If you are using the FILEDEF command to 
relate a data control block (DCB) in a program to an input or output 
file, you may need to supply some of the file format information, such 
as the record length and block size, on the FILEDEF command line. For 
example, if you have coded a DCB macro for an output file as follows: 

OOTFILE DCB DDNAME=OOT, MACRF=PM,DSORG=PS 

then, when you are issuing a FILEDEF for this ddname, you must specify 
the format of the file. To create an output file on disk, blocked in OS 
simulated data set format, you could issue: 

filedef out disk myoutput file aU (recfm fb Irecl 80 block 1600 
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To punch the output file onto cards, you would issue: 

f iledef out punch (Irecl 80 recfm f 

You must supply file format information on the FILEDEF command line 
whenever it is not supplied on the DCB macro, except for existing disk 
files. 

PERM: Usually, when you execute one of the language processors, all 
existing file definitions are cleared. If the development of a program 
requires you to recompile and re-execute it frequently, you might want 
to use the PERM option when you issue file definitions for your input 
and output files. For example: 

cp spool punch to * 

filedef indd disk test file a1 (Irecl 80 perm 

filedef outdd punch (Irecl 80 perm 

In this example, since you spooled your virtual punch to your own 
virtual card reader, output files are placed in your virtual reader. You 
can either read or delete them. 

All file definitions issued with the PERM option stay in effect until 
you log off, specifically clear those definitions, or redefine them: 

filedef indd clear 

filedef outdd tapl (Irecl 80 

In the above example, the definition for INDD is cleared; ODTDD is 
redefined as a tape file. 

When you issue the command: 

filedef * clear 

all file definitions are cleared, except those you enter with the PERM 
option. 

When a program abends, or when you issue the HX Immediate command, 
all file definitions are cleared, including those entered with the PERM 
option- 

DISP MOD: When you issue a FILEDEF command for an output file and assign 
it a CMS file identifier that is identical to that of an existing CMS 
file, then when anything is written to that ddname the existing file is 
replaced by the new output file. If you want, instead, to have new 
records added to the bottom of the existing file, you can use the DISP 
MOD option: 

filedef outdd disk new update a1 (disp mod 

MEMBER: If the file you want to read is a member of an OS partitioned 
data set (or a CMS MACLIB or TXTLIB) , you can use the MEMBER option to 
specify the membername; for example: 

filedef test c dsn sys1 maclib (member test 

defines the member TEST from the OS macro library SYS1. MACLIB. 

AOXPROC: This option allows an auxiliary processing routine to receive 
control during I/O operating. It is valid only when FILEDEF is executed 
by an internal program call and cannot be entered on a terminal command. 
For details on how to use this option of the FILEDEF command, see the 
VM/370 System Programmer2.s Guide. 
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Creating CMS Files From OS Data Sets 

If you have data sets on OS disks, or on tapes or cards, you can copy 
then into CMS files so that you can edit, modify, or manipulate them 
with CMS commands. The CMS MOVEFILE command copies OS (or CMS) files 
from one device to another. You can move data sets from any valid input 
device to any valid output device. 
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Before using the MOVEFILE command, you must define the input and 
output data sets or files and assign them ddnames using the FILEDEF 
command. If you use the ddnames INMOVE and OOTMOVE, then you do not 
need to specify the ddnames when you issue the MOVEFILE command. For 
example, the following sequence of commands copies a CMS disk file into 
your virtual card punch: 

filedef inmove disk diskin file a1 

filedef outmove punch 

movefile 

The result of these commands is effectively the same as if you had 
issued the command: 

punch diskin file (noheader 

The example does, however, illustrate the basic relationship between the 
FILEDEF and MOVEFILE commands. In addition to the MOVEFILE command, if 
the OS input data set is on tape or cards, you can use the TAPPDS or 
READCARD command to create CMS files. These are also discussed below. 

COPYING SEfiOENTIAL DATA SETS FROM DISK: The MOVEFILE command copies a 

sequential OS disk data set from a read-only OS disk into an integral 

CMS file on a CMS read/write disk. You use FILEDEF commands to identify 
the input file disk mode and data set name: 

filedef inmove c1 dsn sales manual 
the CMS output file's disk location and fileid: 

filedef outmove disk sales manual a1 
and then you issue the MOVEFILE command: 

movefile 

COPYING PARTIIIQNED DATA SETS FRQH DISK: The MOVEFILE command can copy 
partitioned data sets (PDS) into CMS disk files, and create separate CMS 
files for each member of the data set. You can have the entire data set 
copied, or you can copy only a selected member. For example, if you 
have a partitioned data set named ASSEMBLE. SOURCE whose members are 
individual assembler language source files, your input file definition 
might be: 

filedef inmove c1 dsn assemble source 

To create individual CMS ASSEMBLE files, you would issue the output file 
definition as: 

filedef outmove disk qprint assemble a1 

Then use the PDS option of the MOVEFILE command: 

movefile (pds 

When the CMS files are created, the filetype on the output file 
definition is used for the filetype and the member names are used 
instead of the CMS filename you specified. 

If you want to copy only a single member, you can use the MEMBER 
option of the FILEDEF command: 

filedef inmove disk assemble source c (member qprint 
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and omit the PDS option on the MOVEFILE command: 

movefile 

Figure 13 summarizes the various ways that you can create CMS files 
from OS data sets. 



Input File: An OS sequential data set named: COMPOTE. TEST. RECORDS 



Source I CMS Conmand Examples 



I CBS Output File 



Disk: 
OS R/O 
C-disk 



Tape: 
181 



Cards 



filedef indd c1 dsn compute test records 
filedef outdd disk compute records a1 
movefile indd outdd 



I . COMPOTE RECORDS A1 

I 

I 



filedef inmove tapl (Irecl 80 
filedef outmove disk test records a1 
movefile 



I TEST RECORDS i1 
I 



tappds newtest compute (nopds 



I HEWTEST COMPOTE A1 



filedef cardin reader 

filedef diskout disk compute cards a1 

movefile cardin diskout 



I COMPOTE CARDS A1 
I 



readcard compute test 



I COMPOTE TEST A1 



Input file: OS partitioned data set named: TEST. CASES 

Members named: SIMPLE, COMPLEX, MIXED 



Source I CMS Command Examples 



I CMS Output File (s) 



Disk: 
OS R/O 

C-disk 



Tape: 
182 



filedef infile disk test cases c1 
filedef outfile disk new testcase a1 
movefile infile outfile (pds 



I SIMPLE TESTCASE A1 
I COMPLEX TESTCASE Al 
I MIXED TESTCASE 



filedef in c1 dsn test cases (member simple 
filedef run disk 
movefile in run 



I FILE ROM Al 

I 

I 



tappds * testrun (tap2 



I SIMPLE TESTBON Al 
I COMPLEX TESTRDN Al 
I MIXED TESTRDN Al 



Figure 13. Creating CMS Files From OS Data Sets 



Using CMS Libraries 

CMS provides two types of libraries to aid in OS FJ^ogJ^aM development: 
• Macro libraries contain macro definitions and/or copy files 



Text, or program 
(compiler output) 



libraries contain relocatable object programs 



These CMS libraries are like OS partitioned data sets; each has a 
directory and members. Since they are not like other CMS files, you 
create, update, and use them differently than you do other CMS files. 
Although these library files are similar in function to OS partitioned 
data sets, OS macros should not be used to update them. Macro libraries 
are discussed below; text libraries are discussed under "TEXT Libraries 
(TXTLIBs)" later in this section. 

A CMS macro library has a filetype of MACLIB. You can create a MACLIB 
from files with filetypes of MACRO or COPY. A MACRO file may contain 
macro definitions; COPY files contain predefined source statements. 



( 
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Hhen you vant to assemble or compile a source p^^ogram that uses macro 
or copy definitions, you must ensure that the library containing the 
code is identified before you invoke the compiler. Otherwise, the 
library is not searched. You identify libraries to be searched using the 
GLOBAL command. For example, if you have two MACLIBs that contain your 
private macros and copy files whose names are TESTMAC MACLIB and 
TESTCOPY MACLIB, you would issue the command: 

global maclib testmac testcopy 

The libraries you specify on a GLOBAL command line are searched in the 
order you specify them. A GLOBAL command remains in effect for the 
remainder of your terminal session, until you issue another GLOBAL 
MACLIB command or re-IPL CMS. To find out what macro libraries are 
currently available for searching, issue the command: 

query maclib 

You can reset the libraries or the search order by reissuing the GLOBAL 
command. 



THE MACLIB COMMAND 

The MACLIB command performs a variety of functions. You use it to: 

• Create the MACLIB (GEN function) 

• Add, delete, or replace members (ADD, DEL, and REP functions) 

• Compress the MACLIB (COMP function) 

• List the contents of the MACLIB (MAP function) 

1, Descriptions of these MACLIB command functions follow. 

GEN Function: The GEN (generate) function creates a CMS macro library 
from input files specified on the command line. The input files must 
have filetypes of either MACRO or COPY. For example: 

maclib gen osmac access time put regequ 

creates a macro library with the file identifier OSMAC MACLIB A1 from 
macros existing in the files with the file identifiers: 

ACCESS f MACROKTIME (MACRO), PUT JMACRO),and REGEQU /MACRO) 
\ COPY / \COPY / j COPY / (COPY j 

If a file named OSMAC MACLIB Al already exists, it is erased. 

Assume that the files ACCESS MACRO, TIME COPY, PUT MACRO, and REGEQU 
COPY exist and contain macros in the following form: 

ACCESS MACRO TIME COPY PUT MACRO REGEQU COPY 






GET *COPY TTIMER PUT XREG 

TTIMER 
PUT *COPY STIMER YREG 

STIMER 
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The resulting file, OSMAC MACLIB Al, contains the members: 



GET 


STIMER 


PUT 


POT 


TTIMER 


REGEQD 



The POT macro, which appears twice in the input to the command, also 
appears twice in the output. The MACLIB command does not check for 
duplicate macro names. If, at a later time, the POT macro is requested 
from OSMAC MACLIB, the first POT macro encountered in the directory is 
used. 

When COPY files are added to MACLIBs, the name of the library member 
is taken from the name of the COPY file, or from the *COPY statement, as 
in the file TIME COPY, above. Hote that although the file REGEQD COPY 
contained two macros, they were both included in the MACLIB with the 
name RE6EQU. When the input file is a MACRO file, the member name(s) are 
taken from macro prototype statements in the MACRO file. 

ADD Function; The ADD function appends new members to an existing macro 
library. For example, assume that OSMAC MACLIB Al exists as created in 
the example in the explanation of the GEN function and the file DCB COPY 
exists as follows: 

*COPY DCB 

DCB macro definition 
♦COPY DCBD 

DCBD macro definition 

If you issue the command: 
maclib add osmac deb 
the resulting OSMAC MACLIB Al contains the members: /* 



GET 


POT 


POT 


REGEQO 


TTIMER 


DCB 


STIMER 


DCBD 



5JP Function: The REP (replace) function deletes the directory entry for 
the macro definition in the files specified. It then appends new macro 
definitions to the macro library and creates new directory entries. For 
example, assume that a macro library MYMAC MACLIB contains the members 
A, B, and C, and that the following command is entered: 

maclib rep mymac a c 

The files represented by file identifiers A MACRO and C MACRO each have 
one macro definition. After execution of the command, MYMAC MACLIB 
contains members with the same names as before, but the contents of A 
and C are different. 

JQJIi Function; The DEL (delete) function removes the specified macro name 
from the macro library directory and compresses the directory so there 
are no unused entries. The macro definition still occupies space in the 
library, but since no directory entry exists it cannot be accessed or 
retrieved. If you attempt to delete a macro for which two macro 
definitions exist in the macro library, only the first one encountered 
is deleted. For example; 

maclib del osmac get put ttimer deb 



< 
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deletes macro names GET, PUT, TTIMEE, and DCB from the directory of the 

macro library named OSMAC HACLIB. Assume that OSHAC exists as in the ADD 

function example. After the above command, OSBAC MACLIB contains the 
following members: 

STIMER 
PUT 

REGEQU 
DCBD 

COMP Function; Execution of a MACLIB command with the DEL or REp 
functions can leave unused space within a macro library. The COMP 
(compress) function removes any macros that do not have directory 
entries. This function uses a temporary file named MACLIB CMSUT1. For 
example, the command: 

maclib comp mymac 

compresses the library MYMAC MACLIB- 

M£ Function: The MAP function creates a list containing the name of 
each macro in the directory, the size of the macro, and its position 
within the macro library. If you want to display a list of the members 
of a MACLIB at the terminal, enter the command: 

maclib map mylib (term 

The default option, DISK, creates a file on your A-disk, which has a 
filetype of MAP and a filename corresponding to the filename of the 
MACLIB. If you specify the PRINT option, the list is spooled to your 
virtual printer. 

Note: TERM and PRINT options will erase the old MAP file. 

Manipulating MACLIB Members 

The following CMS commands have MEMBER options, which allow you to 
reference individual members of a MACLIB: 

• PRINT (to print a member) 

• PUNCH (to punch a member) 

• TYPE (to display a member) 

• FILEDEF (to establish a file definition for a member) 

You can use the CMS editor to create MACRO and COPY files and then 
use the MACLIB command to place the files in a library. Once they are 
in a library, you can erase the original files. 

To extract a member from a macro library, you can use either the 
PUNCH or the MOVEFILE command. If you use the PUNCH command you can 
spool your virtual card punch to your own virtual reader: 

cp spool punch to * 
Then punch the member: 

punch testmac maclib (member get noheader 
and read it back onto disk: 

readcard get macro 
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In the above example, the member was punched with the NOHEADER option of 
the PUNCH command, so that a name could be assigned on the READCARD 
command line. If a header card had been created for the file, it would 
have indicated the filename and filetype as GET MEMBER. 

If you use the MOVEFILE command, you must issue a file definition for 
the input member name and the output macro or copy name before entering 
the MOVEFILE command: 

filedef inmove disk testcopy maclib (member enter 

filedef outmove disk enter copy a 

movefile 

This example copies the member ENTER from the macro library TESTCOPY 
MACLIB into a CMS file named ENTER COPY. 

When you use the PUNCH or MOVEFILE commands to extract members from 
CMS MACLIBs, each member is followed by a // record, which is a MACLIB 
delimiter. You can edit the file and use the DELETE subcommand to 
delete the // record. 

If you wish to move the complete MACLIB to another file, use the 
COPYFILE command. 

Sisten MACLIBs 

The macro libraries that are on the system disk contain CMS and OS 
assembler language macros that you may want to use in your programs: 

• CMSLIB MACLIB contains the CMS macros. 

I • DMSB20 MACLIB contains the CMS macros for VM/370 Basic System 
Extensions (Program No. 5748-XX8) . 

• OSMACRO MACLIB contains the OS macros that CMS supports or simulates 
or those that require no CMS support. 

• 0SMACR01 MACLIB contains the macros CMS does not support or simulate. 

(You can assemble programs in CMS that contain these macros, but you 
must execute them in an OS virtual machine.) 

• TSOMAC MACLIB contains TSO macros. 

• DOSMACRO MACLIB contains macros used in CMS/DOS. 

To obtain a list of the macros in any of these libraries, use the MAP 
function of the MACLIB command. 



USING OS MACRO LIBRARIES 

If you want to assemble source programs that contain macro statements 
that are defined in macro libraries on your OS disks, you can use the 
FILEDEF command to identify them to CMS so that you can name them when 
you issue the GLOBAL command. For example, the commands: 

filedef cmslib disk temp maclib c dsn test asm macros 
global maclib temp 

allow you to access the macro library TEST. ASM. MACROS on the OS disk 
accessed as your C-disk. 
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Assembling Programs in CMS 

To assemble assembler language source programs into object module 
formatr you can use the ASSEMBLE command, and specify assembler options 
on the command line; for example: 

assemble myf ile (print 

assembles a source program named MYFILE ASSEMBLE and directs the output 
listing to the printer. All of the ASSEMBLE command options are listed 
in the 11^370 CMS Command and Macro Reference. 

When you invoke the ASSEMBLE command specifying a file with the 
filetype of ASSEMBLE, CMS searches all of your accessed disks, using the 
standard search order, until it locates the specified file. When the 
assembler creates its output listing and text deck, it creates files 
with filetypes of LISTING and TEXT, and writes them onto disk according 
to the following priorities: 

1. If the source file is on a read/write disk, the TEXT and LISTING 
files are written onto that disk. 

2. If the source file is on a read-only extension of a read/write 
disk, the TEXT and LISTING files are written onto the parent disk. 

3. If the source file is on any other read-only disk, the TEXT and 
LISTING files are written onto the A-disk. 

In all of the above cases, the TEXT and LISTING files have a filename 
that is the same as the input ASSEMBLE file. 

The input and output files used by the assembler are assigned by 
FILEDEF commands that CMS issues internally when the assembler is 
invoked. If you issue a FILEDEF command using one of the assembler 
ddnames before you issue the ASSEMBLE command, you can override the 
default file definitions. 

The ddname for the source input file (SYSIN) is ASSEMBLE. If you 
enter: 

filedef assemble reader 
assemble sample 

then the assembler reads your input file from your card reader, and 
assigns the filename SAMPLE to the output TEXT and LISTING files. 

You could assemble a source file directly from an OS disk by 
entering: 

filedef assemble disk myfile assemble b4 dsn os source file 
assemble myfile 

In this example, the CMS file identifier MYFILE ASSEMBLE is assigned to 
the data set OS. SOURCE. FILE and then assembled. 

LISTING and TEXT are the ddnames assigned to the SYSPRINT and SYSLIN 
output of the assembler. You might assign file definitions to override 
these defaults as follows: 

filedef listing disk assemble listfile a 
filedef text disk assemble textfile a 
assemble source 

In this example, output from the assembly of the file, SOURCE ASSEMBLE, 
is written to the files, ASSEMBLE LISTFILE and ASSEMBLE TEXTFILE. 
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The ddnames PUNCH and CMSLIB are used for SYSPDNCH and SYSLIB data 
sets. PUNCH output is produced when you use the DECK option of the 
ASSEMBLE command. The default file definition for CMSLIB is the macro 
library CMSLIB MACLIB, but you must still issue the GLOBAL command if 
you want to use it. 



Executing Programs 

After you have assembled or compiled a source program you can execute 
the TEXT files that were produced by the assembly or compilation. You 
may not, however, be able to execute all your OS programs directly in 
CMS. There are a number of execution- time restrictions placed on your 
virtual machine by VM/370. You cannot execute a program that uses: 

• Multitasking 

• More than one partition 

• Teleprocessing 

• ISAM macros to read or write files 

The above is only a partial list, representing those restrictions with 
which you might be concerned. For a complete list of restrictions, see 
the IMZ370 Planning and System Generation Guide. 

EXECUTING TEXT FILES 

TEXT files, in CMS, are relocatable, and can be executed simply by 
loading them into virtual storage with the LOAD command and using the 
START command to begin execution. For example, if you have assembled a 
source program named CREATE, you have a file named CREATE TEXT. You can 
issue the command: 

load create 

which loads the relocatable object file into storage, and then, to 
execute it, you can issue the START command: 

start 

In the case of a simple program, as in the above example, you can 
load and begin execution with a single command line, using the START 
option of the LOAD command: 

load create (start 

When you issue the START command or LOAD command with the START 
option, control is passed to the first entry point in your program. If 
you have more than one entry point and you want to begin execution at an 
entry point other than the first, you can specify the alternate entry 
point or CSECT name on the START command: 

start create2 

When you issue the LOAD command specifying the filename of a TEXT file, 
CMS searches all of your accessed disks for the specified file. 

If your program expects a parameter list to be passed (via register 
1) , you can specify the arguments on the START command line. If you 
enter arguments, then you must specify the entry point: 

start * name1 
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When you specify the entry point as an asterisk (*) it indicates that 
you want to use the default entry point. 

Defining In£ut and Output Files 

You can issue the FILEDEF command to define input and output files any 
time before you begin program execution. You can issue all your file 
definitions before loading any TEXT files, or issue them during the 
loading process. You can find out what file definitions are currently 
in effect by issuing the FILEDEF command with no operands: 

filedef 

You can also use the FILEDEF operand of the QUERY command. 



TEXT LIBRARIES (TXTLIBS) 

You may want to keep your TEXT files in text libraries, that have a 
filetype of TXTLIB. Like MACLIBs, TXTLIBs have a directory and members. 
TXTLIBs are created and modified by the TXTLIB command, which has 
functions similar to the MACLIB command: 

• The GEN function creates the TXTLIB. 

• The ADD function adds members to the TXTLIB. 

• The DEL function deletes members and compresses the TXTLIB. 

• The MAP function lists members. 

There is no REP function; you must use a DEL followed by an ADD to 
replace an existing member. The CHS commands that recogni2e HACLIBs as 
special filetypes also recognize TXTLIBs, and allow you to display, 
print, or punch TXTLIB members. 

The TXTLIB command reads the object files as it writes them into the 
library, and creates a directory entry for each entry point or CSECT 
name. If you have a TEXT file named MYPROG, which has a single routine 
named BEGIN, and create the TXTLIB named TESTLIB as follows: 

txtlib gen testlib myprog 

TESTLIB contains no entry for the name MYPROG; you must specify the 
membername BEGIN to reference this TXTLIB member. 

When you want to load members of TXTLIBs into storage to execute them 
(just as you execute TEXT files), you must issue the GLOBAL command to 
identify the TXTLIB: 

global txtlib testlib 
load begin (start 

When you specify more than one TXTLIB on the GLOBAL command line, the 
order of search is established for the TXTLIBs. However, if the AOTO 
option is in effect (it is the default) , CMS searches for TEXT files 
beforie searching active TXTLIBs. 

When the TXTLIB command processes a TEXT file, it writes an LDT 
(loader terminate) card at the end of the TEXT file, so that when a load 
request is issued for a TXTLIB member, loading terminates at the end of 
the member. If you add OS linkage editor control statements to the TEXT 
file (using the CMS editor) before you issue the TXTLIB command to add 
the file to a TXTLIB, the control statements are processed as follows: 
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NAME: A NAME statement causes the TXTLIB Goamand to create the directory 
entry for the member using the specified name. Thereafter, when you want 
to load that member into storage or delete it from the TXTLIB you must 
refer to it by the name specified on the NAME statement. 

ENTRY; If you use an ENTRY statement, the entry point you specify is 
validated and checked for a duplicate- If the entry point name is valid 
and there are no duplicates in the TEXT file, the entry name is written 
in the LDT card. Otherwise, an error message is issued. When this 
member is loaded, execution begins at the entry point specified. (See 
the following "Determining Program Entry Points.") 

ALIAS: An entry is created in the directory for the ALIAS name you 
specify. A maximum of 16 alias names can be used in a single text deck. 
You may load the single member and execute it by referring to the alias 
name, but you cannot use the alias name as the object of V-type address 
constant (VCON) , because the address of the member cannot be resolved. 

SETSSI; Information you specify on the SETSSI card is written in bytes 
26 through 33 of the LDT card. 

All other OS linkage editor control statements are ignored by the 
TXTLIB command and written into the TXTLIB member. When you attempt to 
load the member, the CMS loader flags these cards as invalid. 



RESOLVING EXTERNAL REFERENCES 

There is no real linkage editor in CMS; the link-edit function, that of 
locating external references and loading additional object modules into 
storage, is performed by the CMS loader. The CMS loader loads files 
into storage as a result of a LOAD or INCLUDE command, or when you issue 
a dynamic load reguest from a program (using the OS macros LOAD, LINK, 
or XCTL) . 

When a file is loaded, the loader checks for unresolved references; 
if there are any, the loader searches your disks for TEXT files with 
filenames that match the external entry name. When it finds a match, it 
loads the TEXT file into storage. If a TEXT file is not found, the 
loader searches any available TXTLIBs for members that match; if a match 
is found, it loads the member. 

If there are still unresolved references, for example, if you load a 
program that calls routines PRINT and ANALYZE but the loader cannot 
locate them, you receive the message: 

THE FOLLOWING NAMES ARE UNDEFINED: 
PRINT 
ANALYZE 

You can issue the INCLUDE command to load additional TEXT files or 
TXTLIB members into storage so the loader can resolve any remaining 
references. For example, if you did not identify the TXTLIB that 
contains the routines you want to call, you may enter the GLOBAL command 
followed by the INCLUDE command: 

global txtlib newlib 
include print analyze (start 

This situation might also occur if you have TEXT files with filenames 
that are different from the CSECT names; you must explicitly issue LOAD 
and INCLUDE commands for these files. 
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At execution time, if there are still any unresolved references, 
their addresses are all set to by the loader, so any attempt to 
address then in a program may result in a program check. 



The LOAD and INCLUDE Coimands 

The INCLUDE command has the same format and option list (with one 
exception) as the LOAD command. The main difference is that when you 
issue the INCLUDE command the loader tables are not reset; if you issue 
two LOAD commands in succession, the second LOAD command cancels the 
effect of the first, and the pointers to the files loaded are lost. 

Conversely, the INCLUDE command, which you must issue when you want 
to load additional files into storage, should not be used unless you 
have just issued a LOAD command. ¥ou may specify as many INCLUDE 
commands as necessary following a LOAD command to load files into 
storage. 



CONTROLLING THE CMS LOADER 

The LOAD and INCLUDE commands allow you to specify a number of options. 
YOU can: 

• Change the entry point to which control is to be passed when 
execution begins (RESET option) . 

• Specify the location in virtual storage at which you want the files 
to be loaded (ORIGIN option) . 

• Control how CMS resolves references and handles duplicate CSECT names 
(AUTO, LIB, and DUP options) . 

• Clear storage to binary zeros before loading files (CLEAR option) . 

When the LOAD and INCLUDE commands execute, they produce a load map, 
indicating the entry points loaded and their virtual storage locations. 
YOU may find this load map useful in debugging your programs. If you do 
not specify the NOMAP option, the load map is written onto your A-disk, 
in a file named LOAD MAP A5. Each time you issue the LOAD command, the 
old file LOAD MAP is erased and the new load map replaces it. If you do 
not want to produce a load map, specify the NOMAP option. 

You can find details about these, and other options under the 
discussion of the LOAD command in IHZiilO CMS Command and Macro 
Reference. 



Loader Control Statements 

In addition to the options provided with the LOAD and INCLUDE commands 
that assist you in controlling the execution of TEXT files, you can also 
use loader control statements. These can be inserted in TEXT files, 
using the CMS editor. The loader control statements allow you to: 

• Set the location counter to specify the addres's at which the next 
TEXT file is to be loaded (SLC statement) . 
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• Modify instructions and constants in a TEXT file, and change the 
length of the TEXT file to accomodate modifications (Replace and 
Include Control Section statements) . 

• Change the entry point (ENTRY statement) - 

• Nullify an external reference so that it dees not receive control 
when it is called, and you do not receive an error message when it is 
encountered (LIBRARY statement) . 

These statements are also described under the LOJD command in YB/370 CMS 
Command and Macro Reference. 



Determining Program Entry; Points 

When you load a single TEXT file or a TXTLIB member, into storage for 
execution, the default entry point is the first CSECT name in the object 
file loaded. You can specify a different entry point at which to start 
execution either on the LOAD (or INCLUDE) command line with the RESET 
option: 

load myprog (reset beta 

where BETA is the alternate entry point of your program, or you can 
specify the entry point on the START command line: 

start beta 

When you load multiple TEXT files (either explicitly or implicitly, 
by allowing the loader to resolve external references) , you also have 
the option of specifying the entry point on the LOAD, INCLUDE, or START . 
command lines. \j 

If you do not specifically name an entry point, the loader determines 
the entry point for you, according to the following hierarchy: 

1. An entry point specified on the START command 

2. The last entry specified with the RESET option on a LOAD or INCLUDE 
command 

3. The name on the last ENTRY statement that was read 

4. The name on the last LDT statement that contained an entry name 
that was read 

5. The name on the first assembler- or compiler-produced END statement 
that was read 

6. The first byte of the first control section loaded 

For example, if you load a series of TEXT files that contain no 
control statements, and do not specify an entry point on the LOAD, 
INCLUDE, or START commands, execution begins with the first file that 
you loaded. If you want to control the execution of program subroutines, 
you should be aware of this hierarchy when you lead programs or when you 
place them in TXTLlBs- 
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CREATING PROGRAM MODULES 

When your programs are debugged and tested, you can use the LOAD and 
INCLUDE commands, in conjunction with the GENMOD command, to create 
program modules. A module is a nonrelocatable file whose external 
references have been resolved. In CMS, these files must have a filetype 
of MODULE. 

To create a program module, load the TEXT files or TXTLIB members 
into storage and issue the GENMOD command: 

load create analyze print 
genmod process 
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In this example, PROCESS is the filename you are assigning the 
module; it will have a filetype of MODULE. You could use any name; if 
you use the name of an existing MODULE file, the old one is replaced. 

To execute the program composed of the source files CREATE, ANALYZE, 
and PRINT, enter: 

process 

If PROCESS reguires input and/or output files, you will have to define 
these files before PROCESS can execute properly; if PROCESS expects 
arguments passed to it, you can enter them following the MODULE name; 
for example: 

process testl 

For more information on creating program modules, see "Section 13. 
Programming for the CMS Environment." 
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USING EXEC PROCEDURES 

During your program development and testing cycle, you may want to 
create EXEC procedures to contain sequences of CMS commands that you 
execute frequently. For example, if you need a number of MACLIBs, 
TXTLIBs, and file definitions to execute a particular program, you might 
have an EXEC procedure as follows: 
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8C0NTR0L ERROR TIME 

SERROR &EXIT SRETCODE 

GLOBAL MACLIB TESTLIB OSMACRO 0SMACR01 

ASSEMBLE TESTA 

PRINT TESTA LISTING 

GLOBAL TXTLIB TESTLIB PROGLIB 

ACCESS 200 E 

SBEGSTACK 

OS, TEST3. STREAM. BETA 

&END 

FILEDEF INDD1 E DSN ? 

FILEDEF INDD2 READER 

FILEDEF ODTFILE DISK TEST DATA A1 

LOAD TESTA (START 

SIF 8RETC0DE = 100 6G0T0 -RET100 

8IF SRETCODE = 200 SGOTO -RET200 

SEXIT SRETCODE 

-RET100 8C0NTIN0E 



-RET200 8C0NTIN0E 



The &CONTROL and SERROR control statements in the EXEC procedure 
ensure that if an error occurs during any part of the EXEC, the 
remainder of the EXEC does not execute, and the execution summary of the 
EXEC indicates the command that caused the error. 

Note that for the FILEDEF command entered with the DSN ? operand, 
you must stack the response before issuing the FILEDEF command. In this 
example, since the OS data set name has more than eight characters, you ,j 
must use the SBEGSTACK control statement to stack it. If you use the ^ 
SSTACK control statement, the EXEC processor truncates all words to 
eight characters. 

When your program is finished executing, the EXEC special variable 
SRETCODE indicates the contents of general register 15 at the time the 
program exited. You can use this value to perform additional steps in 
your EXEC procedure. Additional steps are indicated in the preceding 
example by ellipses. 

For detailed information on creating EXEC procedures, see "Part 3. 
Learning to Use EXEC." 



i 
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Section 9. Developing DOS Programs underCMS 



You can use CMS to create, compile, execute and debug DOS programs 
written in assembler, COBOL, or PL/I programming languages. CMS 
I simulates many functions of the Disk Operating System (DOS/VSE) so that 
you can use the interactive facilities of VM/370 to develop your 
programs, and then execute them in a DOS virtual machine. 

This section tells you how to use the CMS/DOS environment. It 

describes the CMS commands you can use to manipulate DOS disks and DOS 

I files and CMS/DOS commands you can use to simulate the functions of 
DOS/VSE: 

The CMS/DOS environment 

Using DOS files on DOS disks 

Using the ASSGN command 

Using the DLBL command 

Using DOS libraries in CMS/DOS 

Using macro libraries 

DOS assembler language macros supported 

Assembling source programs 

Link-editing programs in CMS/DOS 

Executing programs in CMS/DOS 

For a practice terminal session using the commands and techniques 
presented in this section, see "Appendix D: Sample Terminal Sessions." 
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The CMS/DOS Environment 



After you have loaded CMS into your 
CMS/DOS environment by issuing: 

set dos on 



virtual machine you can enter the 



If you want to access a DOS system residence volume during your CMS/DOS 
terminal session, you should link to and access the disk that contains 
the DOS SYSRES before you issue the SET command. For example, if you 
share the system residence volume with other users and it is in your 
directory at virtual address 390, you would issue the command: 

access 390 g 

and then issue the SET command as follows: 
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set dos on g 

to indicate that the SYSRES is located on your G-disk. If you are going 
to use the CMS/DOS librarian facilities to access any of the libraries 
on the system residence volune, you must enter the CMS/DOS environment 
this way. 

If you are using CMS exclusively for DOS applications, you could put 
the ACCESS and SET DOS ON commands in your PROFILE EXEC. 

If you are going to use access method services functions in CMS/DOS, 
or execute functions that read or write VSAM data sets, you must use the 
¥SAM option of the SET DOS ON command: 

set dos on g (vsam 

When you are using CMS/DOS, you can use your virtual machine just as 
you would if you were in the CMS environment; but you cannot execute any 
CMS commands or program modules that load and/or use OS macros. The 
SCRIPT command, for example, uses OS macros, and is therefore invalid in 
the CMS/DOS environment. 

You have, however, in addition to the CP and CMS commands available, 
I a series of commands that simulate DOS/VSE functions. Except for the 
DLBL and DOSLIB commands, these commands or operands should only be 
issued in the CMS/DOS environment. 

The CMS/DOS commands are summarized in Figure 15. 

DL/I in the CMS/DOS Environment 

Batch DL/I programs can be written and tested in the CMS/DOS 
environment. This includes all programs written in COBOL, PL/I, and 
Assembler language. 

Data base description generation and program specification block 
generation can also be executed. However, the application control block 

I generation must be submitted to a DOS/VSE virtual machine for execution. 
The data base recovery and reorganization utilities must also be 

I executed in a DOS/VSE virtual machine- 

This support provides the ability to: 

• Interactively code DL/I control blocks and application programs that 
contain imbedded DL/I calls. 

• Store and maintain macros used to generate DL/I control blocks, and 
programs created under CMS, in the CMS library. Production libraries 
are thus isolated from the test environment. 

• Modify and compile programs using the CMS/DOS text manipulation and 
EXEC facilities. 

• Link-edit and execute batch DL/I programs either interactively or in 
CMSBATCH. Online DL/I application programs requiring access to 

I CICS/VS must be submitted to a DOS/VSE virtual machine for 
link-editing, cataloging, and execution. 

The following restrictions apply: 

• All the existing guidelines and restrictions that apply to VSAM data 
set creation, maintenance, and application program use apply to DL/I 
data sets. 
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Function 



ASSGN I Relates system and programmer logical units to physical 
devices. 

DLBL I Relates a program ddname (filename) to a real disk file 
so you can perform input/output operations on it. 

DOSLIB I Lists or deletes phases from a cns/COS phase library, or 
compresses the library. 

DOSLKED I Link-edits CMS TEXT files or DOS phases from system or 
private relocatable libraries. 

DSERV I Displays the directories of DOS libraries. 

DOSPLI I An EXEC procedure that invokes the DOS/VS PL/I compiler. 

ESERV I An EXEC procedure that invokes the ESERV utility functions 
on edited assembler language macros. 

FCOBOL I An EXEC procedure that invokes the DOS/VS COBOL compiler. 

FETCH I Loads executable phases from a DOSLIB or DOS library into 
storage for execution, and optionally starts execution. 

GLOBAL i Hhen you vant DOSLIBs searched for executable phases or 
macro libraries searched for macro definitions, you must 
identify them with the GLOBAL command. 

LISTIO I Displays the current assignments of system and programmer 
logical units, and optionally creates an EXEC file to 
contain the information. 

OPTION I Sets or changes the options in effect for the DOS/VS 
COBOL compiler. 

QUERY I Use QOERY command operands to list current DLBL defintions 
(QUERY DLBL) , to determine whether or not you are in 
the CMS/DOS environment (QUERY DOS) , the setting of the 
UPSI byte (QUERY OPSI) , the DOSLIBs identified by GLOBAL 
commands (QUERY DOSLIB or QUERY LIBRARY) , the current 
number of lines per page (QUERY DOSLNCNT) , which options 
are in effect for the COBOL compiler (QUERY OPTION) , or to 
find out whether you have set a virtual partition size 
(QUERY DOSPART) . 

PSERV I Creates CMS files with a filetype of PROC from the DOS/VS 
procedure library, or displays, prints or punches 
procedures. 

RSERV I Copies a relocatable module from a DOS library and places 
it in a CMS file with a filetype of TEXT, or displays, 
prints, or punches modules. 

SET I The SET command has operands that allow you to enter or 

leave the CMS/DOS environment (SET DOS ON or SET DOS OFF), 
to set the number of SYSLST lines per page (SET DOSLNCNT) , 
to set the UPSI byte (SET UPSI) , and to set a virtual 
partition size (SET DOSPART) . 

SSERV I Creates CMS COPY files from books on DOS source statement 
libraries. 

: : 1 

Figure 15. CMS/DOS Commands and CMS Commands with Special Operands for 
CMS/DOS 
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• The CMS/DOS restriction on writing to sequential files applies to 

SHSAM and HSAM. 

• To assemble a DBD or PSB under CMS/DOS, you must first copy the 
DBDGEN and PSBGEN macros from the DOS/VSE source statement library to 
a CMS MACLIB. 

For more information about using DL/I in the CMS/DOS environment, see 
Mh^I DOS^VS Generation Information. 

Using DOS Files on DOS Disks 

You can have DOS disks attached to your virtual machine by a directory 
entry or you can link to a DOS disk with the LINK command. You can use 
the ACCESS command to assign a mode letter to the disk: 

access 155 b 

and the RELEASE command to release it: 

release b 

Except for VSAM disks, you cannot write on DOS disks, or update DOS 
files on them. You can, however, execute programs and CMS/DOS commands 
that read from these files, and you can use the LISTDS command to 
display the file- ids of files on a DOS disk; for example: 

listds b 

You can also verify the existence of a particular file. For example, if 
the file-id is NEW. TEST. DATA you can enter: 

listds new test data b 

You can use this form only if the file-id has one- to eight-character 
qualifiers separated by periods. If the file-id of the DOS file you 
want to verify contains embedded blanks, for example NEW. TEST DATA, then 
you have to enter the LISTDS commands with a question mark: 

listds ? b 
CMS responds: 

ENTER DATA SET NAME: 
and you can enter the exact file-id: 

new. test data 

If the data set exists, you receive a response: 

FM DATA SET NAME 
B NEW. TEST DATA 



READING DOS FILES 

Under CMS/DOS, you can execute programs that read DOS sequential (SAB) 
files; you can also execute programs that read and write VSAM files. 
You cannot, however, execute programs to read direct (DAM) or indexed 
sequential (ISAM) DOS files- 
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Complete information on using CMS to access and manipulate VSAM files 
is described in "Section 10. Using Access Method Services and VSAM In 
CMS and CMS/DOS." The discussion below lists the restrictions placed on 
reading SAM files. 



Restrictions on Reading DOS Disk Files in CMS 

CMS cannot read DOS files that: 

• Have the input security indicator on. 

• Contain more than 16 user labels and/or data extents. (If the file 
has user labels, they occupy the first extent; therefore the file 
must contain no more than 15 data extents.) 

• Are multivolume files. Multivolume files are read as single-volume 
files. End of volume is treated as end of file. There is no 
end-of-volume switching. 

• Have user labels. User labels in user-labeled files are bypassed. 

CMS does net support duplicate volume labels; you cannot access more 
than one volume with the same six-character label while you are using 
CMS/DOS. 



CREATING CMS FILES FROM DOS LIBRARIES 

You can create CMS files from existing DOS files on DOS disks. CMS 
simulates the DOS librarian functions DSERV, RSERV, SSERV, ESERV, and 
PSERV with commands of the same names; you can use these CMS/DCS 
commands to create CMS files from relocatable, source statement, or 
procedure libraries located either on the DOS system residence volume or 
in private libraries. The functions are fully described later in this 
section. 



Copying DOS Disk and Tape Data Files 

If you want to create CMS files from DOS files that are not cataloged in 
libraries or from DOS files on tape, you can use the MOVEFILE command. 
The MOVEFILE command allows you to copy a file from one device to 
another device of the same or a different type. Before issuing the 
MOVEFILE command, the input and the output files must be described to 
CMS with the FILEDEF command- 

The MOVEFILE and FILEDEF commands are described and examples are 
given of how to use them in "Section 8. Developing CS Program Under 
CMS." The procedures are the same for copying DOS files as for OS data 
sets. You must, however, keep the following in mind: 

• Since DOS files on DOS disks do not contain ELKSIZE, RECFM, or LRECL 
options, these options must be specified via the FILEDEF command; 
otherwise, defaults of BLOCKSIZE=32760 and RECFM=U are assigned. 
LRECL is not used for RECFM=U files. 

• If a DOS file-id does not follow OS naming conventions (that is, one- 
to eight-byte qualifiers with each qualifier separated by a period; 
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up to 44 characters including periods), you must use the DSN ? 
operand of FILEDEF and the ? operand of LISTDS to enter the DCS 
file- id. 



Copxilia Modules from DOS Library or SYSIN Ta£es 

You can create individual CMS files for DCS modules from a DOS 
library distribution tape or DOS SYSIN tape. Ose the VMFDOS command. 
The VMFDOS command can create a CMS file for each DOS module that 
exists, and the CMS filename corresponds to the DOS module name. You 
can restore individual modules, groups of modules, or the entire 
module set. 

For DOS library distribution tapes, the VMFDOS command restores 
modules from either system or private (relocatable and/or source 
statement) libraries. The created CMS files have a filetype of 
'TEXT* if they are from a relocatable library. They have a filetype 
of 'MACRO' if they are from a source statement library. 

For DOS SYSIN tapes, modules containing a period as the second 
character (for example, 'A.') of a DOS 'CATALx' control statement 
have a filetype of 'MACRO'. All other files have a filetype of 

•TEXT*. 

The VMFDOS command is described in the VM^370 Plannina and System 
Generation Guide. 



leading in Real Card Decks 

If you have DOS files or source programs on cards, you can create CMS 
files directly by having these cards read into the real system card 
reader. You direct the cards to your virtual machine by punching a 
CP ID card in this format: 

ID HARMONY 

and placing this card in front of your card deck. When the cards 
appear in your virtual card reader, you can read them onto your CBS 
A-disk with the READCARD command: 

readcard dataproc assemble 

You can use the editor to remove any DOS control cards that may be 
included in the deck. 



Osina Tajges in CMS/DOS 

See "Tape Labels in CMS" for a description of CMS tape label 
processing for CMS/DOS tape files. The support for tape labels is 
only for files defined by a DTFMT macro. If you do not use this 
macro, CMS bypasses IBM standard labels on input tapes and writes a 
tape mark over any existing labels on an output tape. The CMS 
LABELDEF command is eguivalent in CMS/DOS to the DOS/VM TLBL control 
statement when standard tape label processing is used. 
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Using the ASSGN Command 

The ASSGN and DLBL connands perfora the same functions for CHS/DOS as 
the ASSGN and DLBL control statements In DOS/VSE. Tou use the ASSGN 
command to designate an I/O device for a system or programmer logical 
unit (SYSxxx) and, if the device is a disk device, you can use the 
DLBL command to establish a real file identification for a symbolic 
filename in a program. The DLBL command is described under "Using 
the DLBL Command." 

In addition to using the ASSGN command to relate real I/O devices 
with symbolic units, you must use it in CMS/DOS to: 

Assign SYSIN or SYSIPT for the input source file for a language 
compiler when you use the DOSPLI or FCOBOL commands. 

Identify the disk, by mode letter, on which a private core image, 
relocatable, or source statement library resides. 
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• assign SYSIN or SYSIPT to the CMS disk on which an ESERV file, 
containing control statements for the ESERV program, resides. 

When you enter the ASSGN command, you must supply the logical unit 
and the device; for example: 

assgn syslOO printer 

assigns the logical unit SYS100 to the printer. When you want to make 
an assignment to a disk device, you must specify the mode letter at 
which the disk is accessed. The command: 

assgn sysOlO b 

assigns the logical unit SYS010 to your B-disk. 

The system logical units you can assign and the valid device types 
you can assign to them in CMS/DOS follow. 

SYSIPT, SYSRpR, SYSIN: These units can be assigned to disk (mode) , TAPE, 
or READER. If you make an assignment to SYSIN, both SYSRDR and SYSIPT 
are also assigned the same device. 

SYSLST: The system logical unit for listings can be assigned to disk 
(mode) , PRINTER, or TAPE. 

SYSLOG: Terminal or operator output or messages can be assigned to 
PRINTER or TERMINAL. CMS/DOS always assigns SYSLOG to TERMINAL by 
default, so you never have to make this assignment except when you want 
to alter it. 

SYSPCH; Punched output, for example text decks, can be assigned to 
PUNCH, disk (mode), or TAPE. 

SYSCLB, SYSRLB, SYSSLB: The system logical units SYSCLB, SYSRLB, and 
SYSSLB can be assigned to private core image, relocatable, and source 
statement libraries, respectively. The only valid assignments for these 
units is to disk (mode). If you want to reference private libraries 
with the DSERV, ESERV, FETCH, SSERV, or RSERV commands, you must assign 
SYSCLB, SYSRLB, or SYSSLB to the disks on which the libraries reside. 



Programmer Logical Units 

You can assign programmer logical units SYSOOO through SYS2m with the 

ASSGN command. This deviates from DOS/VS, where the number of 

programmer logical units varies according to the number of partitions. 



MANIPULATING DEVICE ASSIGNMENTS 

Besides assigning I/O devices, the ASSGN command can also negate a 
previous assignment: 

assgn syspch ua 

or specify that, for a given device, no real I/O operation is to be 
performed during the execution of a program: 

assgn sys009 ign 
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When you release a disk from your virtual machine, any assignments made 
to that disk are unassigned. 

You can find out the current assignments for system and programmer 
logical units with the LISTIO command, which lists all the system or 
programmer logical units, even those that are unassigned: 

listio 

To list only currently assigned units, enter: 

listio a 

To find out the current assignment of one specific unit, for example 
SYSIOO, enter: 

listio syslOO 

With the EXEC option of the LISTIO command, you can create a disk 
file containing the list of assignments. The SLISTIO EXEC that is 
created contains two EXEC numeric variables, 81 and 82, for each unit 
listed. For example, if you entered the command: 

listio sysOSl (exec 

then the file SLISTIO EXEC may contain the record: 

81 82 SYS081 PRINTER 

When you use the STAT option, LISTIO lists, for disk devices, whether 
the disk is read-only or read/write; for example: 

listio syslOO 
SYSIOO B R/W 

indicates that SYSIOO is assigned to the B-disk, which is a read/write 
disk. 

You can cancel all current assignments by leaving the CMS/DOS 
environment and then re-entering it: 

set dos off 
set dos on 



VIRTUAL MACHINE ASSIGNMENTS 

When you assign a physical device type to a system or programmer logical 
unit, CMS relates the device to your virtual machine configuration; you 
receive an error message if you try to assign a logical unit to a device 
not in your configuration. For example, if you are using the ASSGN 
command to assign a logical unit to a disk file, you must specify the 
access mode letter of the disk. If the disk is not accessed, the ASSGN 
command fails. 

For another example, if you issue: 

assgn syspch punch 

the punch specified is your own virtual machine card punch. The actual 
destination of punched output then depends on the spooling 
characteristics of the punch; if it is spooled to another user or to *, 
then no real cards are punched, but virtual card images are placed in 
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the virtual reader of the destination userid, which may be another 
virtual machine or your own- 

CMS supports only one reader, one punch, and one printer; you cannot 
make any assignments for multiple output devices in CMS/DOS. ihen you 
make an assignment for a logical unit that has already been assigned, it 
replaces the current assignment. 



Using the DLBL Command 

Use the DLBL command to supply CMS/DOS with specific file identification 
information for a disk file that is going to be used for input or 
output. For any DLBL command you issue, you must previously have issued 
an ASSGN command for the disk, specifying a system or programmer logical 
unit. The basic relationship is: 

assgn SYSxzx mode 

dlbl filename mode DSN ? (SYSxxx 

Both the SYSxxx and the mode values must match on the ASSGN and DLBL 
commands; the disk on which the file resides must be accessed at mode. 

The filename on the DLBL command line, called a ddname in CHS/DOS, 
corresponds to the symbolic name for a file in a program. If you want to 
reference a private DOS library, you must use one of the following 
ddnames: 

System 

LSaical Unit l!i:len§l§ 

SYSCLB IJSYSCL 

SYSRLB IJSYSHL 

SYSSLB IJSYSSL 



ENTERING FILE IDENTIFICATIONS 

When you issue the DLBL command you must identify the file, by file-id 
(for a DOS file) or by file identifier (for a CMS file) . The keywords 
DSN and CMS indicate whether it is a DOS file or a CMS file, 
respectively. 

If the file is a DOS file residing on a DOS disk, you can enter the 
DLBL command in one of two ways. For example, for a file named 
TEST. INPUT you could enter either: 

assgn syslOI d 

dlbl infile d dsn test input (sys101 

— or — 

assgn syslOI d 
dlbl infile d dsn ? (syslOI 
ENTER DATA SET NAME: 
test. input 

For any DOS file with a file-id that contains embedded blanks or 
hyphens, you must use the "DSN ?" form. 
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When you issue a DLBL command for a CMS file, you enter the filename 
and filetype following the keyword CMS: 

assgn sys102 a 

dlbl outfile a cms new output (sys102 

In this example, if SYS102 is defined as an output file for a program, 
the output is written to your CMS A-disk in a file named NEW OOTPDT- 

you can, for convenience, use a CMS default file identifier. If you 
enter: 

dlbl outfile a cms (sys102 

then the output filetype defaults to that of the ddname and the filename 
to FILE. So, this output file is named FILE OOTFILE. 



Clearing and Displaying File Definitions 

You can clear a DLBL definition for a file by using the CLEAR operand of 
the DLBL command: 

dlbl outfile clear 

To clear all existing definitions, except those entered with, the PERM 
option, you can enter: 

dlbl * clear 

This command is issued by the assembler and the language processors when 
they complete execution. Definitions entered with the PERM option must 
be individually cleared. 

Whenever you use the HX Immediate command to halt the execution of a 
program, the DLBL definitions in effect are cleared, including those 
entered with the PERM option. 

You can find out what definitions are currently in effect by issuing 
the DLBL command with no operands: 

dlbl 

or, you can use the QUERY command with the DLBL operand. 



Using DOS Libraries in CMS/DOS 

CMS/DOS provides you with the capability of using various types of files 
from DOS system or private libraries- You can copy, punch, display at 
the terminal, or print: 

• Books from system or private source statement libraries using the 
SSERV command 

• Relocatable modules from system or private relocatable libraries 
using the RSER? command 

• Procedures from the system procedure library using the PSERV command 
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You can also: 



Copy and de-edit macros from system and private E sublibraries using 
the ESERV command 

Access the directories of system or private libraries using the DSEHV 
command 

Link-edit relocatable modules from system or private relocatable 
libraries with the DOSLKED command 

Read core image phases from system or private core image libraries 
into storage for execution using the FETCH command 



THE SSERV COMMAND 

If you have cataloged source programs or copy files on the system source 
statement library and you want to use CMS to modify and test them, you 
can copy them into CMS files using the SSERV command. For example, 
suppose you want to copy a book named PROCESS from the A sublibrary on 
the system residence volume. The DOS system residence is in your 
virtual machine configuration at virtual address 350, and you have 
accessed it as your F-disk- First, to indicate to CMS/DOS that the 
system residence is on your F-disk, you enter: 

set dos on f 

then you can enter the SSERV command, specifying the sublibrary 
identification and the book name: 

sserv a process 

This creates, from the A sublibrary, a file named PROCESS COPY and 
places it on your A-disk- If the book contained assembler language 
source statements you would want the filetype to be ASSEMBLE, so you may 
enter: 

sserv a process assemble 

If you want to copy a book from a private source statement library, 
you must first use the ASSGN and DLBL commands to make the library known 
to CMS/DOS. For example, to obtain a copy file from a private library 
on a DOS disk accessed as your D-disk, enter: 

assgn sysslb d 

dlbl ijsyssl d dsn ? (sysslb 
ENTER DATA SET NAME: 
program. test library 

Now, when you enter the SSERV command: 

sserv t setup copy 

the book named SETUP in the T sublibrary of PROGRAM. TEST LIBRARY is 
copied into a CMS file named SETUP COPY. If SETUP is not found in the 
private library, then CMS searches the system library, if it is 
available. 
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THE RSERV COMMAND 

In CMS/DOS, to manipulate relocatable modules that have been cataloged 
either on the system or a private relocatable library you must first 
copy them into CMS files with the RSERV command. You can link-edit 
■odules directly from DOS relocatable libraries, but if you want to add 
or modify linkage editor control statements for a module, you must place 
the control statements in a CMS file. 

If you are copying a relocatable module from the system relocatable 
library, then you should make sure that you have indicated the system 
residence disk when you entered the CMS/DOS environment: 

set dos on f 

then you can issue the RSERV command specifying the name of the 
relocatable module you want to copy: 

rserv rtna 

The execution of this command results in the creation of a CMS file 
named RTNA TEXT on your A-disk. 

If you want to copy a relocatable module from a private relocatable 
library, you must first use the ASSGN and DLBL commands to make the 
private library known to CMS/DOS: 

assgn sysrlb d 

dlbl ijsysrl d dsn reloc lib (sysrlb 

Then, issue the RSERV command for a specific module in that library: 

rserv testrtna 

to create the CMS file TESTRTNA TEXT from the module named TESTRTNA. If 
the module TESTRTNA is not found in RELOC. LIB, CMS searches the system 
library, if it is available. 



THE PSERV COMMAND 

If you want to copy DOS cataloged procedures into CMS files to use, for 
example, in preparing job streams for a DOS/VS virtual machine, you can 
use the PSERV command: 

pserv prepjob 

This command creates a CMS file on your A-disk; the file is named 
PREPJOB PROC. To copy a procedure from the procedure library you must 
have entered the CMS/DOS environment specifying a disk mode for the 
system residence volume. 

You cannot execute DOS/VS procedures directly from the CMS/DCS 
environment. However, if you modify a procedure, you can punch it to a 
I virtual machine that is running a DOS/VSE system, and execute it there. 
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THE ESERV COMMAND 

The CMS/DOS ESERV command is actually an EXEC procedure that calls the 
I DOS/VSE ESERV utility program. To use the ESERV program, you first must 
use the CMS Editor to create a file with a filetype of ESERV that 
contains the ESERV control statements you want to execute. For example, 
if you want to write a de-edited copy of the macro DTFCD onto your 
A-disk, you might create a file named DTFCD ESERV, with the record: 

PUNCH E. DTFCD 

I As when you submit ESERV jobs in DOS/VSE, column 1 must be blank. 

Then, you must assign SYSIN to the device on which the ESERV source 
file resides, usually your A-disk: 

assgn sysin a 

Then you can enter the ESERV command specifying the filename of the 
ESERV file: 

eserv dtfcd 

No other ASSGN commands are reguired; the CMS/DOS ESERV EXEC makes 
default assignments for SYSPCH and SYSLST to disk. 

To copy and de-edit macros from a private E sublibrary, issue the 
ASSGN and DLBL commands to identify the library. For example, to 
identify a source statement library named TEST. MACROS on the DOS disk 
accessed as the C-disk, enter: 

assgn sysslb c 

dlbl ijsyssl c dsn test macros (sysslb 

The SYSLST output is contained in a CMS file with the same filename 
as the ESERV file and a filetype of LISTING; you must examine the 
LISTING file to see if the ESERV program executed successfully. You can 
either edit it (using the CMS editor), or display its contents with the 
TYPE command: 

type dtfcd listing 

The SYSPCH output is contained in a file with the same name as the 
ESERV file and a filetype of MACRO. If you want to punch ESERV output 
to your virtual card punch, make an assignment of SYSPCH to PUNCH. 

When you use the PUNCH or DSPCH ESERV control statements, CATAL.S, 
END, or /* records may be inserted in the output file. When you use the 
MACLIB command to add the MACRO file to a CMS macro library, these 
statements are ignored. 

See "Using Macro Libraries" for information on creating and 
manipulating CMS macro libraries. 

THE DSERV COMMAND 

You can use the DSERV command to examine the contents of system or 
private libraries. If you do not specify any options with it, the DSERV 
command creates a disk file, named DSERV MAP, on your A-disk. You can 
use the PRINT or TERM options to specify that the directory list is 
either to be printed on your spooled printer or displayed at your 
terminal. You can also use the SORT option to create a list in 
collating seguence. 
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In order to examine a system directory, you must have entered the 
CMS/DOS environment specifying the mode letter of the DOS system 
residence: 

set dos on f 

If you want to examine the directory of a private source statement, 
core image, or relocatable library you must issue the ASSGN and DLEL 
commands establishing SYSSLB, SYSCLB, or SYSRLB before using the DSEBV 
command. 

For example, to display at your terminal an alphameric list of 
procedures cataloged on the system procedure library, you would issue: 

dserv pd (sort term 

If the directory you are examining is for a core image library, you 
can specify a particular phase name to ascertain the existence of the 
phase: 

dserv cd phase $$bopen (term 

To list the directory of a private source statement library, you 
would first issue the ASSGN and DLBL commands: 

assgn sysslb b 

dlbl ijsyssl b dsn test source (sysslb 

then enter the DSERV command: 

dserv sd 

The CMS file, DSERV MAP A, that is created in this example contains the 
directory of the private source statement library TEST. SOURCE. 



OSING DOS CORE IMAGE LIBRARIES 

You can load core image phases from DOS core image libraries into 
virtual storage and execute them under CMS/DOS- Since CMS cannot write 
directly to DOS disks, linkage editor output under CMS/DOS is placed in 
a special CMS file called a DOSLIB. When you execute the FETCH command 
in CMS/DOS you can load phases from either system or private DOS core 
image libraries as well as from CMS DOSLIBs. More information on using 
the FETCH command is contained under "Executing Programs in CMS/DOS." 



Using Macros Libraries 

DOS/VS macro libraries cannot be accessed directly by the VM/370 
assembler. If you want to assemble DOS programs in CMS/DOS that use DOS 
macro or copy files that are on the system or a private macro library 
you must first create a CMS macro library (MACLIE) containing the macros 
you wish to use- Since the process of creating a CMS MACLIB from the 
DOS system source statement library (E sublibrary) can be very 
time-consuming, you should check with your installation's system 
programmer to see if it has already been done, and to verify the 
filename of the macro library, so that you can use it in CMS/DOS. 

Note: The DOS/VSE PL/I and DOS/VSE COBOL compilers executing in CMS/DOS 
cannot read macro or copy files from CMS MACLIBs. 
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If you want to extract DOS system macros to modify them for your 
private use, or if you want to use macros from a private library in CMS, 
you must use the procedure outlined below to create the HACLIB files. 



CMS MACLIBS 



A CMS macro library has a filetype of MACLIB. You can create a MACLIB 
from files with filetypes of MACRO or COPY. A MACRO file may contain 
macro definitions; COPY files contain predefined source statements. 

When you want to assemble a source program that uses macro or copy 
definitions, you must ensure that the library containing the code is 
identified before you invoke the assembler. Otherwise, the library is 
not searched. You identify libraries to be searched using the GLOBAL 
command. For example, if you have two MACLIBs that contain your private 
macros and copy files whose names are TESTMAC MACLIB and TESTCOPY 
MACLIB, you would issue the command: 

global maclib testmac testcopy 

The libraries you specify on a GLOBAL command line are searched in the 
order you specify them. A GLOBAL command remains in effect for the 
remainder of your terminal session, or until you IPL CMS. To find out 
what macro libraries are currently available for searching, issue the 
command: 



) 



query maclib 

You can reset the libraries or the search order by reissuing the GLOBAL 
command. 



CREATING A CMS MACLIB 



To create a CMS macro library, each macro or copy file you want included 
in the MACLIB must first be contained in a CMS file with a filetype of 
COPY or MACRO. If you are creating a CMS MACLIB file from a DOS library 
you must use the SSERV command to copy a file from any source statement 
library other than an E sublibrary, or use the ESERV command to copy and 
de-edit^a macro from an E sublibrary. The SSERV command uses a default 
filetype of COPY; the ESERV command uses a default filetype of MACRO. 

The following example shows how to copy macros from various sources 
and shows how to create and use the CMS MACLIB that contains these 
macros. 



1. Enter the CMS/DOS environment with the DOS system residence 
disk accessed as mode C: 



on a 



set dos on c 



) 



2. Copy the macro book named OPEN from the A sublibrary of the system 
source statement library: 

sserv a open 
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3. Establish a private source statement library: 

access 351 d 

assgn sysslb d 

dlbl ijsyssl d dsn ? (sysslb \ 

test source. lib 

a. Issue the SSERV command for a macro in the M sublibrary of TEST 
SOURCE. LIB: 

sserv ffl releas 

5. Create an ESERV file to copy from the E sublibrary: 

edit contrl eserv 

NEW FILE 

EDIT: 

input punch contrl 

file 

6. Execute the ESERV command: 

assgn sysin a 
eserv contrl 

7. Create a CMS macro library named MYDOSMAC from the files just 
created, which are named OPEN COPY, RELEAS COPY, and CONTRL MACRO: 

maclib gen mydosmac open releas contrl 

8. TO use these macros in an assembler language program, you must 
indicate that this MACLIB is accessible before assembling a source 
file: 

global maclib mydosmac a 



THE MACLIB COMMAND 

The MACLIB command performs a variety of functions. You use it to: 

• Create the MACLIB (GEN function) 

• Add, delete, or replace members (ADD, DEL, and REP functions) 

• Compress the MACLIB (COMP function) 

• List the contents of the MACLIB (MAP function) 

Descriptions of these MACLIB command functions follow. 

GEN Inaction: The GEN (generate) function creates a CMS macro library 
from input files specified on the command line. The input files must 
have filetypes of either MACRO or COPY. For example: 

maclib gen mymac get pdump put regegu 

creates a macro library with the file identifier MYMAC MACLIB A1 from 
macros existing in the files with the file identifiers: 

GET / MACRO), PDOMP /MACRO\,PUT / MACRO \,and REGEQO j MACRO\ 
\COPY / (COPY / (COPY / \ 



COPY / 
If a file named MYMAC MACLIB A1 already exists, it is erased. 
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Assume that the files GET MACRO^ PDOMP COPY, PUT MACRO, and REGEQU 
COPY exist and contain macros in the following form: 



) 



GET MACRO 


PDOMP COPY POT MACRO REGEC 


|0 COPY 


GET 


♦COPY PDDMP POT XREG 
PDOMP 




WAIT 


♦COPY WAIT YREG 
WAIT 




le resulti 


ng file, MYMAC MACLIB A1, contains the 


member: 


GET 


WAIT 




HAIT 


POT 




PDDMP 


REGEQO 





The WAIT macro, which appears twice in the input to the command, also 
appears twice in the output. The MACLIB command does not check for 
duplicate macro names. If, at a later time, the WAIT macro is reguested 
from MYMAC MACLIB, the first WAIT macro encountered in the directory is 
used. 

When COPY files are added to MACLIBs, the name of the library member 
is taken from the name of the COPY file, or from the ♦COPY statement, as 
in the file PDDMP COPY, above. Note that although the file REGEQO COPY 
contained two macros, they were both included in the MACLIB with the 
name REGEQO. When the input file is a MACRO file, the member name is 
taken from the macro prototype statement in the MACRO file. 

HP Function; The ADD function appends new members to an existing macro 
library. For example, assume that MYMAC MACLIB A1 exists as created in 
the example in the explanation of the GEN function and the file DTFDI 
COPY exists as follows: 

♦COPY DTFDI 

DTFDI macro definition 
♦COPY DIMOD 

DIMOD macro definition 

If you issue the command: 

maclib add mymac dtfdi 
the resulting MYMAC MACLIB A1 contains the members: 



GET 


POT 


WAIT 


REGEQO 


PDDMP 


DTFDI 


WAIT 


DIMOD 



RJ£ Function: The REP (replace) function deletes the directory entry for 
the macro definition in the files specified. It then appends new macro 
definitions to the macro library and creates new directory entries. For 
example, assume that a macro library TESTMAC MACLIB contains the members 
A, B, and C, and that the following command is entered: 

maclib rep testmac a c 

The files represented by file identifiers A MACRO and C MACRO each have 
one macro definition. After execution of the command, TESTMAC MACLIB 
contains members with the same names as before, but the contents' of A 
and C are different. 
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Ulk Function; The DEL (delete) function removes the specified macro naie 
from the macro library directory and compresses the directory so there 
are no unused entries. The macro definition still occupies space in the 
library, but since no directory entry exists, it cannot be accessed or 
retrieved. If you attempt to delete a macro for which two macro 
definitions exist in the macro library, only the first one encountered 
is deleted. For example: 

maclib del mymac get put wait dtfdi 

deletes macro names GET, PUT, WAIT, and DTFDI from the directory of the 
macro library named MYMAC MACLIB. Assume that MIMAC exists as in the ADD 
function example. After the above command, MYMAC MACLIB contains the 
following members: 

PDUMP 
WAIT 
REGEQU 
DIMOD 

COMP Function; Execution of a MACLIB command with the DEL or REP 
functions can leave unused space within a macro library. The COMP 
(compress) function removes any macros that do not have directory 
entries. This function uses a temporary file named MACLIB CMS0T1. For 
example, the command: 

maclib comp mymac 

compresses the library MYMAC MACLIB. 

MAP Function: The MAP function creates a list containing the name of 
each macro in the directory, the size of the macro, and its position 
within the macro library. If you want to display a list of the members 
of a MACLIB at the terminal, enter the command: 

maclib map mymac (term 

The default option, DISK, creates a file on your A-disk which hias a 
filetype of MAP and a filename equal to the filename of the MACLIB. If 
you specify the PRINT option, then a copy of the map file is spooled to 
your virtual printer as well as being written onto disk. 



Manipulating MACLIB Members 



The following CMS commands supply a MEMBER option, which 
reference individual members of a MACLIB: 

• PRINT (to print a member) 

• PUNCH (to punch a member) 

• TYPE (to display a member) 

• FILEDEF (to establish a file definition for a member) 



allows you to 



You can use the CMS editor to create the MACRO and COPY files and 
then use the MACLIB command to place them in a library. Once they are 
in a library, you can erase the original files. 

To "extract a member from a macro library, you can use either the 
PUNCH or the MOVEFILE command. If you use the PUNCH command you can 
spool your virtual card punch to your own virtual reader: 

cp spool punch to * 



c 
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Then punch the member: 

punch testmac maclib (member get noheader 
and read it back onto disk: 

readcard get macro 

In the above example, the member was punched with the NOHEADER option of 
the PUNCH command, so that a name could be assigned on the READCftBD 
command line- If a header had been created for the file, it would have 
indicated the filename and filetype as GET MEMBER. 

If you use the MOVEFILE command, you must issue a file definition for 
the input member name and the output macro or copy file before entering 
the MOVEFILE command: 

filedef inmove disk testcopy maclib (member enter 

filedef outmove disk enter copy a 

movefile 

This example copies the member ENTER from the macro library TESTCOPY 
MACLIB A into a CMS file named ENTER COPY. 

When you use the POHCH or MOVEFILE commands to extract members from 
CMS MACLIBs, each member is followed by a // record, which is a MACLIB 
delimiter. You can edit the file and use the DELETE subcommand to 
delete the // record. 

If you wish to move the complete MACLIB to another file, use the 
COPYFILE command. 

System MACLIBs 

The macro libraries that are on the system disk contain CMS, DOS, and OS 
assembler language macros. The MACLIBs are: 

• CMSLIB MACLIB, which contains the CMS macros. 

• DMSB20 MACLIB contains the CMS macros for VM/370 Basic System 
Extensions (Program No. 57U8-XX8) . 

• DOSMACRO MACLIB, which contains DOS/VS macros that CMS/DOS routines 
use. 

• OSMACRO MACLIB, 0SMACR01 MACLIB, and TSOMAC MACLIB, which are used by 
OS programmers. 



DOS Assembler Language Macros Supported 

I Figure 16 lists the DOS/VSE assembler language macros supported by 
CMS/DOS. You can assemble source programs that contain these macros 
under CMS/DOS, provided that you have the macros available in either 
your own or a shared CMS macro library. The macros whose functions are 
described in the "Function" column with the term "no-op" are supported 
for assembly only; when you execute programs that contain these macros, 
I the DOS/VSE functions are not performed,. To accomplish the macro 
I function you must execute the program in a DOS/VSE virtual machine. 
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r 

1 Macro 


SVC 


Function 


i CALL 


— 


Pass control to another program 


1 CANCEL 


06 


Terminate processing 


1 CDLOAD 


65 


Load a VSAM phase 


1 CHECK 


— 


Verify completion of a read or write operation 


1 CLOSE/ 


— 


Deactivate a data file 


1 CLOSER 


— 




1 CNTRL 


_. 


Control a physical device 


1 COMRG 


33 


Return address of background partition 
communication region 


1 DEQ 


U1 


no— op 


1 DEQB 


9 


Release a resource 


1 DTFxxi 


— 


Establish file definitions 


1 DO MP 


— 


Dump storage and registers and terminate processing 


1 ENQ 


42 


no-op 


1 ENQB 


2 


Protect a resource 


1 EOJ 


14 


Terminate processing normally 


1 ERET 


~ 


Provide an error routine 


1 EXCP 


00 


Execute a channel program 


1 EXIT PC 


17 


Return from program check routine 


1 EXIT AE 


95 


Return from abnormal termination routine 


1 FCEPGODT 


86 


no— op 


1 FETCH 


01 


Load and pass control to a phase 




02 


Load and pass control to a logical transient 


1 FREEVIS 


62 


Release user free storage 


1 GENL 


_ ■ . 


Generate a phase directory list 


1 GET 


— 


Access a sequential file 


1 GETVIS 


61 


Obtain user free storage 


1 GETIME 


34 


Get the time of day 


1 JDOMP 


— 


Dump storage and registers and terminate processing 


1 LOAD 


04 


Read a phase into storage 


1 MVCOM 


05 


Modify bytes in the partition communication region 


1 NOTE 


— 


Manage data set access 


1 OPEN/ 


— 


Activate a data file 


1 OPENR 


— 




1 PAGEIN 


87 


no— op 


1 PDDMP 


— 


Dump storage and registers and continue processing 


1 PFIX 


67 


no-op 


1 PFREE 


68 


no-op 


1 POINTR 


— 


Position a file for reading 


1 POINTS 


— 


Reposition a file to its beginning 


1 POINTW 


— 


Position a file for writing 


1 POST 


40 


Post the event control block 


1 PRTOV 


— 


Control printer overflow 


1 POT 


— 


Write to a sequential file 


1 PDTR 


— 


Communicate with the system operator 


1 READ 


— 


Access a sequential file 


1 RELEASE 


64 


Release a system resource 


1 RELPAG 


85 


no-op 


1 RELSE 


— 


Skip to begin reading next block 


1 RETORN 


— 


Return control to calling program 


1 RONMODE 


66 


Check if program is running real or virtual 


1 SECTVAL 


75 


Obtain a sector number 


1 SEIZE 


22 


no— op 


1 SETIME 


10/24 


no— op 


1 SETPFA 


71 


no— op 


1 *The declarative 


macros supported are: 


1 DTFCN, 


DTFCD, 


DTFPR, DTFDI, DTFMT, DTFSD, DTFCP, and DTFSL 



I Figure 16. DOS/VSE Macros Supported by CMS (Part 1 of 2) 
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1 Macro 




SVC 


Function 


1 STXIT AB 




37 


Provide or terminate linkage to abnormal ending 


1 PC 




16 


routine 


1 IT 




20 


no— op 


1 OC 




18 


no-op 


1 TRACK FREE 


36 


no-op 


1 TRACK HOLD 


35 


no— op 


1 TRONC 




— 


Skip to begin writing next block 


1 TTIMER 




52 


Return a in Register (effectively a noop) 


1 OSE 




63 


Reserve a system resource 


1 WAIT 




07 


Wait for the completion of I/C 


1 WRITE 




— 


Write to a sequential file 


1 XXMODi 




— 


Create Logical IOCS routine inline 


1 iThe DOS 


logic 


modules supported are: 


1 CDMOD, 


PRMOD, 


DIMOD, MTMOD, SDMODxx, and CPMOD 



I Figure 16^ DOS/VSE Macros Supported by CMS (Part 2 of 2) 



Assembling Source Programs 

I If you are a DOS/VSE assembler language programmer using CMS/DOS, you 
I should be aware that the assembler used is the VM/370 assembler, not the 
DOS/VSE assembler. The major difference is that the VM/370 assembler, 
invoked by the ASSEMBLE command, is designed for interactive use, so 
that when you assemble a program, error messages are displayed at your 
terminal when compilation is completed, and you do not have to wait for 
a printed listing to see the results- You can correct your source file 
and reassemble it immediately. When your program assembles without 
errors, you can print the listing. 

To specify options to be used during the assembly, you enter them on 
the ASSEMBLE command line. So, for example, if you do not want the 
output LISTING file placed on disk, you can direct it to the printer: 

assemble myfile (print 

All of the ASSEMBLE command options are listed in VM/370 CMS Command and 
Macro Reference. 

When you invoke the ASSEMBLE command specifying a file with a 
filetype of ASSEMBLE, CMS searches all of your accessed disks, using the 
standard search order, until it locates the file. When the assembler 
creates the output LISTING and TEXT files, it writes them onto disk 
according to the following priorities: 

1- If the source file is on a read/write disk, the TEXT and LISTING 
files are written onto the same disk. 

2- If the source file is on a read-only disk that is an extension of a 
read/write disk, the TEXT and LISTING files are written onto the 
parent disk. 

3. If the source is on any other read-only disk, the TEXT and LISTING 
files are written onto the A-disk. 

In all of the above cases, the filenames assigned to the TEXT and 
LISTING files are the same as the filename of the input file. 

I The output files used by the assembler are defined via FILEDIF 

commands issued by CMS when it calls the assembler. If you issue a 
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FILEDEF command using one of the assembler ddnames before you issue the 
ASSEMBLE command, you can override the default file definitions. 

The ddname for the source input file is ASSEMBLE. If you enter: 

filedef assemble reader 
assemble sample 

then the assembler reads your input file from your card reader, and 
assigns the filename SAMPLE to the output TEXT and LISTING files. You 
can use this method to assemble programs directly from DOS sequential 
files on DOS disks. For example, to assemble a source file named 
EOSPROG from a DOS disk accessed as a C-disk, you could enter: 

filedef assemble c dsn dosprog (recfm f Irecl 80 
assemble dosprog 

Again, the name you assign on the ASSEMBLE command may be anything; the 
assembler uses this name to assign filenames to the TEXT and LISTISG 
output files. 

LISTING and TEXT are the ddnames assigned to the SYSLST and SYSPCH 
output of the assembler. You might issue file definitions to override 
these defaults as follows: 

filedef listing disk assemble listfile a 
filedef text disk assemble textfile a 
assemble source 

When these commands are executed, the output from the assembly of the 
file SOURCE ASSEMBLE is written to the disk files ASSEMBLE LISTFILE and 
ASSEMBLE TEXTFILE. 

Link-editing Programs in CMS/DOS 

When the assembler or one of the language compilers executes, the object 
module produced is written to a CMS disk in a file with a filetype of 
TEXT- The filename is always the same as that of the input source file. 
These TEXT files (sometimes referred to as decks, although they are not 
real card decks) can be used as input to the linkage editor or can be 
the target of an INCLUDE linkage editor control statement. 

You can invoke the CMS/DOS linkage editor with the DOSLKED command, 
for example: 

doslked test testlib 

where TEST is the filename of either a DOSLNK or TEXT file (that is, a 
file with a filetype of either DOSLNK or TEXT) or the name of a 
relocatable module in a system or private relocatable library. TESTLIB 
indicates the name of the output file which, in CMS/DOS, is a phase 
library with a filetype of DOSLIB- 

When you issue the DOSLKED command, CMS first searches for a file 
with the specified name and a filetype of DOSLNK. If none are found, it 
searches the private relocatable library, if you have assigned one (you 
must issue an ASSGN command for SYSRLB and use the ddname IJSSYRL in a 
DLBL statement) . If the module is still not found, CMS searches all of 
your accessed disks for a file with the specified name and a filetype of 
TEXT- Last, CMS searches the system relocatable library, if it is 
available (you must enter the CMS/DOS environment specifying the mode 
I letter of the DOS/VSE system residence if you want to access the system 
libraries) - 
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LINKAGE EDITOR INPOT 

You can place the linkage editor control statements ACTIOK, PHASE, 
INCLUDE, and ENTRY in a CMS file with a filetype of DOSLNK. When you 
use the INCLUDE statement, you may specify the filename of a CMS TEXT 
file or the name of a module in a DOS relocatable library: 

INCLUDE XYZ 

or you may use the INCLUDE control statement to indicate that the object 
code follows: 

INCLUDE 

(CMS TEXT file) 

A typical DOSLNK file, named CONTROL DOSLNK, might contain the 
following: 

ACTION REL 
PHASE PROGMAIN,S 
INCLUDE SUBA 
PHASE PROGA,* 
INCLUDE SUBB 

When you issue the command: 

doslked control 

the linkage editor searches the following for the object files SUBA and 
SUBB: 

• A DOS private relocatable library, provided you have issued the ASSGN 
and DLBL commands to identify it: 

assgn sysrlb d 

dlbl ijsysrl d dsn ? (sysrlb 

• Your CMS disks for files with filenames SUBA and SUBB and a filetype 
of TEXT 

• The system relocatable library located on the DOS system residence 
volume (if it is available) 

Link-editing TEXT Files 

When you want to link-edit individual CMS TEXT files, you can insert 
linkage editor control statements in the file using the CMS editor and 
then issue the DOSLKED command: 

edit rtnb text 

EDIT: 

input include rtnc 

file 

doslked rtnb mydoslib 

When the above DOSLKED command is executed, the CMS file RTNB TEXT is 
used as linkage editor input, as long as there is no file named RTNB 
DOSLNK. The ACTION statement, however, is not recognized in TEXT files. 

You can also link-edit relocatable modules directly from a DOS system 
or private relocatable library, provided that you have identified the 
library. If you do this, however, you cannot provide control statements 
for the linkage editor. 
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To link-edit a relocatable module from a DOS private library and add 
linkage editor control statements to it, you could use this procedure: 

1. Identify the library and use the RSERV command to copy the 
relocatable module into a CMS TEXT file. In this example, the 
module RTNC is to be copied from the library OBJ. MODS: 

assgn sysrlb e 

dlbl ijsysrl e dsn obj mods (sysrlb 

rserv rtnc 

2. Create a DOSLNK file, insert the linkage editor control statements, 
and copy the TEXT file created in step 1 into it using the GETFILE 
subcommand: 

edit rtnc doslnk 
input action rel 
get file rtnc text a 
file 

3. Invoke the linkage editor with the DOSLKED command: 

doslked rtnc mydoslib 

Alternatively, you could create a DOSLNK file with the following 
records: 

ACTION REL 
INCLUDE RTNC 

and link-edit the modtile directly from the relocatable library. If you 
do not need a copy of the module on a CMS disk, you might want to use 
this method to conserve disk space. 

/ 
When the linkage editor is reading modules, it may encounter a blank i,( 

card at the end of a file, or a * (comment) card at the beginning of a 

file. In either case, it issues a warning message indicating an invalid 

card, but continues to complete the link-edit. 



LINKAGE EDITOR OOTPDT: CMS DOSLIBS 

The CMS/DOS linkage editor always places the link-edited executable 
phase in a CMS library with a filetype of DOSLIB. You should specify 
the filename of the DOSLIB when you enter the DOSLKED command: 

doslked progO templib 

where PROGO is the relocatable module you are link-editing and TEMPLIB 
is the filename of the DOSLIB. 

If you do not specify the name of a DOSLIB, the output is placed in a 
DOSLIB that has the same name as the DOSLNK or TEXT file being 
link-edited. In the above example, a CMS DOSLIB is created named 
TEMPLIB DOSLIB, or, if the file TEMPLIB DOSLIB already exists, the phase 
PROGO is added to it. 

DOSLlBs can contain relocatable core image phases suitable for 
execution in CMS/DOS. Before you can access phases in it, you must 
identify it to CMS with the GLOBAL command: 



global doslib templib permlib 
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Hhen CMS is searching for executable phases, it searches all DOSLIEs 
specified on the last GLOBAL DOSLIB command line. If you have named a 
number of DOSLIBs, or if any particular DOSLIB is very large, the time 
required for CMS to fetch and execute the phase increases. You should 
use separate DOSUBs for executable phases, whenever possible, and then 
specify only the DOSLlBs you need on the GLOBAL command. 

When you link-edit a module into a DOSLIB that already contains a 
phase with the same name, the directory entry is updated to point to the 
new phase. However, the space that was occupied by the old phase is not 
reclaimed. You should periodically issue the command: 

doslib comp libname 

where libname is the filename of the DOSLIB, to compress the DOSLIB and 
delete unused space. 



LIuKMS lMi5£ Maps 

The DOSLKED command also produces a linkage editor map, which it writes 
into a CMS file with a filename that is that of the name specified on 
the DOSLKED command line and a filetype of MAP. The filemode is always 
A5. If you do not want a linkage editor map, use the NOMAP option on 
the ACTION statement in a DOSLNK file. 



Executing Programs in CMS/DOS 



After you have assembled or compiled a source program and link-edited 
the TEXT files, you can execute the phases in your CMS virtual machine. 
You may not, however, be able to execute all your DOS programs directly 
in CMS. There are a number of execution-time restrictions placed on your 
virtual machine by VM/370. You cannot execute a program that uses: 

• Multitasking 

• More than one partition 

• Teleprocessing 

• ISAM macros to read or write files 

• CMS module files created by DOS programs 

The above is only a partial list, representing those restrictions with 
which you might be concerned. For a complete list of restrictions, see 
the VM^370 Plannina and System Generation Guide. 



EXECUTING DOS PHASES 

You can load executable phases into your CMS virtual machine using the 
FETCH command. Phases must be link-edited before you load them; they 
must have been link-edited with ACTION REL. When you issue the FETCH 
command, you specify the name of the phase to be loaded: 

fetch myprog 

Then you can begin executing the program by issuing the START command: 

start 

Section 9. Developing DOS Programs Under CMS 175 



Or, you can fetch a phase and begin executing it on a single command 
line: 

fetch Fi^og2 (start 

When you use the FETCH command without the START option, CMS issues a 
message telling you at what virtual storage address the phase is loaded: 

PHASE PR0G2 ENTRY POINT AT LOCATION 020000 

Location X*20000» is the starting address of the user program area for 
CHS; relocatable phases are always loaded starting at this address 
unless you specify a different address using the ORIGIN option of the 
FETCH command: 

fetch prog3 (origin 22000 
start 

The program PR0G3 executes beginning at location 22000 in the CHS user 
program area. 



SEARCH ORDER FOR EXECUTABLE PHASES 

When you execute the FETCH command, CMS searches for the phase name you 
specify in the following places: 

1- In a DOS/VS private core image library on a DOS disk. If you have 

a private library you want searched for phases, you must identify 

it using the ASSGN and DLBL commands, using the logical unit 
SYSCLB: 

assgn sysclb d 

dlbl ijsyscl d dsn ? (sysclb 

2, In CMS DOSLIBs on CHS disks. If you want DOSLIBs searched for 
phases, you must use the GLOBAL command to identify them to 
CHS/DOS: 

global doslib templib mylib 

You can specify up to eight DOSLIBs on the GLOBAL command line. 

3. On the DOS system residence core image library. If you want the 
system core image library searched you must have entered the 
CMS/DOS environment specifying the mode letter of the system 
residence: 

set dos on z 

When you want to fetch a core image phase that has copies in both the 

core image library and a DOSLIB, and you want to fetch the copy from the 

CMS DOSLIB, you can bypass the core image library by entering the 
command: 

assgn sysclb ua 

When you need to use the core image library, enter: 

assgn sysclb c 

where C is the mode letter of the system residence volume. You do not 
need to reissue the DLBL command to identify the library. 



( 
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MAKING I/O DEVICE ASSIGNMENTS 

If you are executing a program that performs I/C, you can use the ASSGN 
command to relate a system or programmer logical unit to a real I/O 
device. As in DOS/VSE, device type assignment in CMS/DOS is dependent 
on device specifications in the program- 

assgn syslst printer 
assgn sys052 reader 

In this example, your program is going to read input data from your 
virtual card reader; the output print file is directed to your virtual 
printer. If you want to reassign these units to different devices, you 
must be sure that the files have been defined as device independent. 

If you assign a logical unit to a disk, you should identify the file 
by using the DLBL command. On the DLBL command, you must always relate 
the DLBL to the system or programmer logical unit previously specified 
in an ASSGN command: 

assgn sys015 b 

dlbl myfile b dsn ? (sysOIS 

When you enter the DLBL command with the ? operand you are prompted to 
enter the DOS file-id. 

You must issue all of the ASSGN and DLBL commands necessary for your 
program's I/O before you issue the FETCH command to load the program 
phase and begin executing. 

SPECIFYING A VIRTUAL PARTITION SIZE 

For most of the programs that you execute in CMS, you do not need to 
specify how large a partition you want those programs to execute in. 
When you issue the START command or use the START option on the FETCH 
command, CMS calculates how much storage is available in your virtual 
machine and sets a partition size. CMS calculates how much storage is 
available in the following manner: 

FREELOWE - (MAINHIGH + (4096 * FRERESPG) ) 

where: 

FREELOWE equals the low extent of allocated storage obtained from the 
top of virtual storage downwards via the DMSFREE system 
request. 

MAINHIGH equals the high extent of allocated storage obtained from the 
low virtual storage upwards via the GETMAIN user request for 
storage. 

FRERESPG equals the amount of storage to be reserved for subsequent 
system requests, in pages. 

In some insta^nces, you may want to control the partition size: 

• For performance considerations 

• Because the default may not leave enough free storage to satisfy the 
GETVIS commands issued by the DOS program or the access method 
services function being executed. 
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You can set the partition size with the DOSPART operand of the SET 
command. For example, after you enter the command: 

set dospart 300k 

all programs that you subsequently execute during this session will 
execute in a 300K partition. In this way you can: 

• Set a smaller partition size for programs that run better in smaller 
partitions. 

• Set a smaller partition size to leave more free storage. If the 
reduction of the DOS partition does not free enough storage for the 
GETVIS commands, a larger virtual machine must be defined. 

If you enter: 

set dospart off 

the CMS calculates a partition size when you execute a program. This is 
the default setting. 

Note that the CMS partition, unlike the DOS partition, is used only for 
the loading and executing of programs invoked by the FETCH or LOAD 
commands. Areas allocated by GETVIS will be assigned addresses outside 
the partition but within the user's virtual machine. 



SETTING THE UPSI BYTE 

If your program uses the user program switch indicator (OPSI) byte, you 
can set it by using the OPSI operand of the CMS SET command. The DPSI 
byte is initially binary zeros. To set it to 1s, enter 

set upsi 11111111 

To reset it to zeros, enter: 

set upsi off 

Any value you set remains in effect for the duration of your terminal 
session, unless you reload CMS (with the IPL command). 



DEBUGGING PROGRAMS IN CMS/DOS 

You can debug your DOS programs in CMS/DOS using the facilities of CP 
and CHS. By executing your programs interactively, you can more quickly 
determine the cause of an error or program abend, correct it, and 
attempt to execute a program again,. 

The CP and CMS debugging facilities are described in "Section 11. How 
¥M/370 Can Help You Debug Your Programs." Additional information for 
assembler language programmers is in "Section 13. Programming for the 
CMS Environment." 
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USING EXEC PROCEDURES IN CMS/DOS 

During your program development and testing cycle, you may want to 
create EXEC procedures to contain sequences of CMS commands that you 
execute frequently- For example, if you need a number of HACLIBs, 
DOSLIBs, and DLBL definitions to execute a particular program, you might 
have an EXEC procedure as follows: 

&CONTflOL ERROR TIME 

SERRO? SEXIT SRETCODE 

GLOBAt MACLIB TESTLIB DOSMAC 

ASSEMBLE TESTA 

PRINT TESTA LISTING 

DOSLKED TESTA TESTLIB 

GLOBAL DOSLIB TESTLIB PROGLIB 

ACCESS 200 E 

ASSGN SYS010 E 

&BEGSTACK 

DOS. TEST3. STREAM. BETA 

SEND 

DLBL DISK1 E DSN ? (SYS010 

ASSGN SYS011 PUNCH 

CP SPOOL PUNCH TO * 

ASSGN SYS012 A 

DLBL ODTFILE A CMS TEST DATA (SYS012 

FETCH TESTA (START 

SIF SRETCODE = 100 &GOTO -RET100 

SIF SRETCODE = 200 SGOTO -RET200 

SEXIT SRETCODE 

-RET100 6C0NTINUE 



-RET200 SCONTINUE 



The SCONTROL and SERROR control statements in the EXEC procedure 
ensure that if an error occurs during any part of the EXEC, the 
remainder of the EXEC does not execute, and the execution summary of the 
EXEC indicates the command that caused the error. 

Note that for the DLBL command entered with the DSN ? operand, you 
must stack the response before issuing the DLBL command. In this 
example, since the DOS file-id has more than eight characters, you must 
use the SBEGSTACK control statement to stack it. If you use the SSTACK 
control statement, the EXEC processor truncates all words to eight 
characters. 

When your program is finished executing, the EXEC special variable 
SRETCODE indicates the contents of general register 15 at the time your 
program exited. You can use this value to perform additional steps in 
your EXEC procedure. Additional steps are indicated in the preceding 
example by ellipses. 

For detailed information on creating EXEC procedures, see "Part 3. 
Learning To Use EXEC." 
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Section 10. Using Access Method Services 
and VSAM under CMS and CMS/DOS 



This section describes how you can use CHS to create and manipulate VSAH 
catalogs, data spaces, and files on OS and DOS disks using access method 

I services. The CMS support is based on DOS/VSE and VSE/VSAM; this means 
that if you are an OS VSAM user and plan to use CMS to manipulate VSAM 
files you are restricted to those functions of access method services 

I that are available under the access method services portion of VSE/VSAM. 

i The control statements you can use are described in the publication 
Using VSE/VSAM Commands and Macros. 

You can use CMS to: 

• Execute the access method services utility programs for VSAH and SAM 
data sets on OS and DOS disks and minidisks. CMS can both read and 
write VSAM files using access method services. 

• Compile and execute programs that read and write VSAH files from DCS 
programs written in the COBOL or FL/I programming languages. 

• Compile and execute programs that read and write VSAH files from OS 
programs written in the VS BASIC, COBOL, or EL/I programming 
languages. 

• Assemble assembler language source programs under CMS that use VSAH 
macros. You must create your own macro library from OS or DOS macro 
libraries. 

VSAM files written under CMS are wholly compatible for reading and 
writing under OS and DOS systems. None of the CMS commands normally used 
to manipulate CMS files are applicable to VSAM files, however. This 
includes such commands as PRINT, TYPE, EDIT, COPYFILE, and so on. 

This section provides information on using the CMS AMSERV command 
ith which you can execute access method services. The discussion is 
ivided as follows: 

"Using the AMSERV command" contains general information. 

"Manipulating OS and DOS Disks for Use With AMSERV" describes how to 
use CMS commands with OS and DOS disks. 

"Defining DOS Input and Output Files" is for CMS/DOS users only. 

"Defining OS Input and Output Files" is for OS users only. 

"Using AMSERV Under CMS" includes notes and examples showing how to 
perform various access method services functions in CMS. 



EXECUTING VSAM PROGRAMS UNDER CMS 

The commands that are used to define input and output data sets for 
access method services (DLBL) and for CMS/DOS users (ASSGN) are also 
used to identify VSAM input and output files for program execution. 
Information on executing programs under CMS that manipulate VSAM files 
is contained in the program product documentation for the language 
processors. These publications are listed in the VM/370 Introduction. 
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Restrictions on the use of access method services and VSAM under CHS 
for OS and DOS users are listed in VM/370 CMS Command and Macro 
Reference^ which also contains complete CMS and CMS/DOS command formats, 
operand descriptions, and responses for each of the commands described 
here. 

When you are going to execute VSAM programs in CMS or CMS/DOS, you 
should remember to issue the DLBL command to identify the master 
catalog, as well as any other program input or output file you need to 
define. 



Using the AMSERV Command 

In CMS, you execute access method services utility programs with the 
AMSERV command, which has the basic format: 

amserv filename 

"filename" is the name of a CMS file that contains the control 
statements for access method services. 

Note: Throughout the remainder of this section the term "AMSERV" is used 
to refer to both the CMS AMSERV command and the OS/VS or DOS/VS access 
method services, except where a distinction is being made between CBS 
and access method services. 

You create an AMSERV file with the CMS editor using a filetype of 
AMSERV and any filename you want; for example: 

edit mastcat amserv 

NEW FILE: 

EDIT: 

input 

The editor recognizes the filetype of AMSERV and so automatically sets 

the margins for your input lines at columns 2 and 72. The sample AMSERV 

file being created in the example above, MASTCAT AMSERV, might contain 
the following control statements: 

DEFINE MASTERCATALOG (NAME (MYCAT) - 
VOLUME (123456) CYL (2) - 
FILE (IJSYSCT) ) 

Note that the syntax of the control statements must conform to the rules 
for access method services, including continuation characters and 
parentheses. The only difference is that the AMSERV file does not 
contain a "/*" for a termination indicator. 

Before you can execute the DEFINE control statement in this AMSERV 
example, you must define the output file, using the ddname IJSYSCT. You 
can do this using the DLBL command.. Since the exact form required in 
the DLBL command varies according to whether you are an OS or a DCS 
user, separate discussions of the DLBL command are provided later in 
this section- All of the following examples assume that any disk data 
set or file that you are referencing with an AMSERV command will have 
been defined by a DLBL command. 

When you execute the AMSERV command, ^ the AMSERV control statement 
file can be on any accessed CMS disk; you do not need to specify the 
filemode and, if you are a DOS user, you do not need to assign SYSIPT. 
The task of locating the file and passing it to access method services 
is performed by CMS. 
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When the AMSERV command is finished processing, you receive the CMS 
ready message, and if there was an error, the return code (from register 
15) is displayed following the "R". For example: 

R (00008) ; 

or, if you are receiving the long form of the ready message, it appears: 

R (00008); T=0.01/0.11 10:50:23 

If you receive a ready message with an error return code, you should 
examine the output listing from AMSERV to determine the cause of the 
error. 

AMSERV output listings are written in CMS files with a filetype of 
LISTING; by default, the filename is the same as that of the input 
AMSERV file. For example, if you have executed: 

amserv mastcat 

and the CMS ready message indicates an error return code, you should 
examine the file MASTCAT LISTING: 

edit mastcat listing 

EDIT: 

locate /idc/#= 

Issuing the LOCATE subcommand twice to find the character string IDC 
will position you in the LISTING file at the first access method 
services message. 

The publication DOS/VS Messages lists and explains all of the 
messages generated by access method services together with the 
associated reason codes. 

Instead of editing the file, you could also use the TYPE command to 
display the contents of the entire file, so that you would be able to 
examine the input control statements as well as any error messages: 

type mastcat listing 

If you need to make changes to control statements before executing 
the AMSERV command again, use the CMS editor to modify the AMSERV input 
file. 

If you execute the same AMSERV file a number of times, each execution 
results in a new LISTING file, which replaces any previous listing file 
with the same filename. 



QatEUi from PRINT, LISTCAT, and LISTCRA 



> 



When you use AMSERV to print a VSAM file, or to list catalog or recovery 
area contents using the PRINT, LISTCAT, or LISTCRA control statements, 
the output is written in a listing file on a CMS read/write disk, and 
not spooled to the printer unless you use the PRINT option of the AMSERV 
command: 

amserv listcat (print 
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If you want to save the output, you should issue the AMSERV command 
without the PRINT option and then use the CMS PRINT command to print the 
LISTING file. 



CONTROLLING AMSERV COMMAND LISTINGS 

The final disposition of the listing, as a printer or disk file, depends 
on how you enter the AMSERV command. If you enter the AMSERV command 
with no options, you get a CMS file with a filetype of LISTING and a 
filename equal to that of the AMSERV input file. This LISTING file is 
usually written on your A-disk, but if your A-disk is full or not 
accessed, it is written on any other read/write CMS disk you have 
accessed. 

If there is not enough room on your A-disk or any other disk, the 
AMSERV command issues an error message saying that it cannot write the 
LISTING file. If this happens, the LISTING file created may be 
incomplete and you may not be able to tell whether or not access method 
services actually completed successfully. In this case, after you have 
cleared some space on a read/write disk, you may have to execute an 
AMSERV PRINT or LISTCAT function to verify the completion of the prior 
job. 

LISTING files take up considerable disk space, so you should erase 
them as soon as you no longer need them. 



AMSERV Command Listing QjBtions 

If you do not want AMSERV to create a disk file from the listing, you 
can execute the AMSERV command with the PRINT option: 

amserv myfile (print 

The listing is spooled to your virtual printer, and no disk file is 
created. You might want to use this option if you are executing a PRINT 
or LISTCAT control statement and expect a very large output listing that 
you know cannot be contained on any of your disks. 

You can also control the filename of the output listing file by 
specifying a second name on the AMSERV command line: 

amserv listcat listcatl 

In this example, the input file is LISTCAT AMSERV and the output listing 
is placed in a file named LISTCATI LISTING. A subsequent execution of 
this same AMSERV file: 

amserv listcat listcat2 

creates a second listing file, LISTCAT2 LISTING, so that the listing 
created from the first execution is not erased. 



i 
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Manipulating OS and DOS Disks for Use with 
AMSERV 

To use CMS VSAM and AMSERV, you can have OS or DOS disks in your virtual 
machine configuration. They can be assigned in your directory entry, or 
you can link to them using the CP LINK command. You must have read/write 
access to them in order to execute any AMSERV function or VSAM program 
that requires opening the file for output or update. 

Before you can use an OS or DOS disk you must access it with the CMS 
ACCESS command: 

access 200 d 

The response from the ACCESS command indicates that the disk is in OS or 
DOS format: 

D (200) R/W - OS 

— or — 

D (200) R/H - DOS 

You can write on these disks only through AMSERV or through the 
execution of a program writing VSAM data sets. Once an OS disk is used 
with AMSERV or VSAM, CMS considers it a DOS disk, so regardless of 
whether you are an OS user, when you access or request information about 
a VSAM disk, CMS indicates that it is a DOS disk. You can still use the 
disk in an OS or DOS system for VSAM data set processing. Although the 
format is not changed, the disk is still subject to any 
incompatibilities that can currently exist between OS and DOS disks. 



DATA AND MASTERCATALOG SHARING 

There are two meanings of "sharing'' that must be defined clearly with 
respect to the CMS support of VSAM. The first is that of the 
SHAREOPTION parameter found in the DEFINE (and ALTER) command for access 
method services. 

The SHAREOPTION keyword enables the VSAM user to define how a 
component will be shared across partitions (users). Since CMS is a 
single-partition, single-user system and there is no data set sharing 
capability in the control program (CP) , the built-in data sharing in 
VSAM is of no value under CMS. However, if the VSAM user specifies 
SHAREOPTION three fewer lines of code will be executed and, therefore, 
that option is recommended. 

The ar6a of sharing most familar to CMS users is that of disk 
(minidisk) read-sharing provided by CP. For the VSAM user under CBS, it 
is still possible to share disks in read-only mode in order to 
read-share VSAM components. However, there is a restriction with 
respect to the VSAM master catalog. That is, only one virtual machine 
may have the disk containing the master catalog in write status. This 
is necessary even if only read functions are being performed during the 
session. This is due to the master catalog updating read statistics at 
close time and, when necessary, writing a new control record in the 
catalog at open time. Under the OS/VS and DOS/VS systems (real) this is 
not a consideration because the master catalog is always on a system 
pack and, therefore, always in write status by that system and by the 
VSAM routines. The virtual machines (OS or DOS) cannot share the VSAM 
catalog since each thinks it is a "real" system and has control of the 
VSAM master catalog. 
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I Under CMS, it is possible to have the master catalog disk read-only. 

1 A bit in the ACB indicates to VSE/VSAM that it is running under CMS. If 
this bit is on, VSAM will not write to the master catalog for either of 
the two cases described above. This allows one or more CMS virtual 
machines to share the VSAM master catalog. This assumes either no other 
virtual machine has the master catalog disk in write status or only one 
virtual machine (DOS, OS, or CMS) has it. 

Multiple CMS users may have the VSAM master catalog disk in read-only 

status but only one virtual machine may have the same in write status. 

With respect to dataset sharing, there is only read-sharing for the CMS 
user. 



DISK COMPATIBILITY 

Since the CMS VSAM support writes VSAM datasets to DOS disks, the 

question of disk compatibility is not one between CMS and DOS nor 

between CMS or OS but rather between DOS and OS disks. In other words, 

I because CMS actually uses VSE/VSAM for processing VSAM datasets, all 
disks used by CMS VSAM are DOS disks. For this reason, we need only 

discuss how DOS and OS disks are compatible and, because they are 

compatible, we can conclude that CHS and OS are also compatible. 

In the format-4 DSCB, there is a bit in the VTOC Indicators (byte 59, 
bit 0) defined by OS/VS to indicate (when OFF) that a format-5 label is 
I included in the VTOC. This bit is always On under DOS/VSE because DCS 
does not maintain the format-5 label. This technique allows OS/VS to 
realize when the format-5 is invalid and that it must recompute free 
space and rewrite the format-5 so that device integrity is maintained. 

Thus, if a disk originally was used (allocated) under OS/VS and, 

I subsequently, with DOS/VSE, further allocation could occur under DOS/VSE 

but with the format-5 ignored and, therefore, no longer valid. If the 

disk was then used under OS/VS and still further allocation performed, 

OS/VS would recognize the fact that the format-5 was not valid 
I (contamination bit turned ON by DOS/VSE) and would rewrite the forfflat-5, 
turning the bit OFF. 

This shows that DOS and OS disks are compatible in that they are 
portable between the two systems, but one of the systems (OS/VS) must 
perform some extra processing (rewriting format-5) prior to using the 
disk if it intends to reallocate using the format-5. 

DOS and OS disks containing VSAM datasets are no exception to this. 

OS and DOS disks containing VSAM datasets that are used (allocated) 
I under CMS are portable among all three systems. Since CMS uses VSE/VSAM 
i code, all disks used under CMS to process VSAM datasets become DOS/VSE 
I disks in that the contamination bit is turned ON as it is when using 

DOS/VSE. 

The term "minidisk" may be interchanged with the word "disk" in the 
I above explanation if we are dealing with "virtual" DOS/VSE and OS/VS 
systems. However, real systems are not aware of, and do not support, 
minidisks. 

It is necessary to distinguish between two types of allocation under 
VSAM. The first refers to actual space allocation on the disk, and the 
second is that within the dataset itself. 

Space for VSAM componepts must be allocated en the DASD device using 
the DEFINE commands. The only component for which the user is able to 

186 IBM VM/370 CMS User's Guide 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp- SD23--902a-1 for 5748-XX8 

allocate space is for the master catalog, a data space, and a nNIQUE 
cluster. In defining the actual DASD space for conponents, there are 
parameters for the DEFINE SPACE command which allows the user to include 
a **secondary allocation" specification. These parameters (CYLIHDERS, 
RECORDS, TRACKS) have this secondary facility only as a syntactic 
compatibility with the OS/VS access method services commands. That is, 
DOS/VSE (and, therefore, CHS) does not perform secondary space 
allocation on a DASD. 

The facility does exist under DOS/VSE (and CMS) to extend data or 
index components through already allocated data space, catalog extents, 
or UNIQUE cluster extents. Thus, the CYLINDERS, TRACKS, and RECORDS 
parameters of the DEFINE commands for alternate indexes, clusters, and 
catalogs do not dynamically allocate DASD space but only extend a 
component through existing space. 



USING VM/370 MINIDISKS 

If you have a VM/370 minidisk in your virtual machine configuration, you 
can use it to contain VSAM files. Before you can use it, it must be 
formatted with the IBCDASDI program or other appropriate operating 
system utility program. When you reguest that a disk be added to your 
virtual machine configuration for use with VSAM files under CMS, you 
should indicate that it be formatted for use with OS or DOS. Or you can 
format it yourself using the IBCDASDI program. A brief example of how to 
do this is given under the following "Using Temporary Disks." The 
IBCDASDI control statements are fully described in the VM/370 Operator's 
Guide. 

Note: If you are an OS user, you should be careful about allocating 
space for VSAM on minidisks. Once you have used CMS AMSERV to allocate 
VSAM data space on a minidisk, you should not attempt to allocate 
additional space on that minidisk using an OS/VS system. OS does not 
recognize minidisks, and would attempt to format the entire disk pack 
and thus erase any data on it. To allocate additional space for VSAM, 
you should use CMS again. If you use the IBCDASDI program to format the 
disk, and use the CYLNO parameter, the entire disk is flagged as full, 
so that OS cannot allocate additional space. Minidisk space allocation 
is fully described in the VM/370 Planning and System Generation Guide. 



USING THE LISTDS COMMAND 

For OS or DOS disks or minidisks, you can use the LISTDS command to 
determine the extents of free space available for use by VSAM. You can 
also determine what space is already in use. You can use this 
information to supply the extent information when you define VSAM files. 

The options used with VSAM disks are: 

• EXTENT, to find out what extents are in use, and 

• FREE, to find out what extents are available. 

For example, if you have an OS disk accessed as a G-disk, and you enter: 
listds g (extent 
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The response might look like: 

EXTENT INFORMATION FOR •VTOC» 0^1 'G' DISK: 

SEQ TYPE CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 

OOO.VTOC 099 00 1881 099 18 1899 19 

EXTENT INFORMATION FOR • PRIVAT. CORE. IMAGE. LIE* ON 'G* DISK: 
SEQ TYPE CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 DATA 000 01 1 049 18 949 949 

EXTENT INFORMATION FOR • SYSTEM. WORK. FILE .NO .6 » ON 'G* DISK: 
SEQ TYPE CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 DATA 050 00 950 051 18 987 38 

YOU could also determine the extent for a particular data set: 

listds ? * (extent 

DMSLDS220R ENTER DATA SET NAME: 

system recorder file 

EXTENT INFORMATION FOR 'SYSTEM RECORDER FILE* ON 'F' DISK: 
SEQ TYPE CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 DATA 102 00 1938 102 18 1956 19 
002 DATA 010 06 206 010 08 208 3 

LISTDS searches all minidisks accessed until it locates the specified 
data set. In this example, the data set occupies two separate extents on 
disk F. If the data set is a multi volume data set, extents on all 
accessed volumes are located and displayed. 

If you want to find the free extents on a particular disk, enter: 

listds g (free 

FREESPACE EXTENTS FOR 'G* DISK: 

CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 

052 00 988 052 01 989 2 

054 02 1028 080 00 1520 493 

081 01 1540 098 18 1880 341 

YOU can use this information when you allocate space for VSAM files. If 
you enter: 

listds * (free 

CMS lists all the free space available on all of your accessed disks. 



USING TEMPORARY DISKS 

When you need extra space on a temporary basis for use with CMS 7SAM and 
AMSERV, you can use the CP DEFINE command to define a temporary minidisk 
and then use the IBCDASDI program to format it. Once formatted and 
accessed, it is available to your virtual machine for the duration of 
your terminal session or until you detach it using the CP DETACH 
command. Remember that anything placed on a temporary disk is lost, so 
that you should copy output that you want to keep onto permanent disks 
before you log off. 
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Formatting a Temporary Disk 

The example below shows a control statement file and an EXEC procedure 
that, together, can be used to format a minidisk with the IBCDASDI 
program. For a complete description of the control statements used, 
refer to the VM^370 Qperator^s Guide. 

The input control statements for the IBCDASDI programs should be 
placed in a CMS file, so that they can be punched to your virtual card 
reader. For this example, suppose the statements are in a CMS file named 
TEMP IBCDASDI: 

DASD198 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=198,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=123U56 

VTOCD STRTADR=185,EXTENT=5 

END 

NOW consider the CMS file named TEMPDISK EXEC: 

SERROR &EXIT 100 

CP DEFINE T3330 198 10 

CP CLOSE C 

CP PORGE READER ALL 

ACC 190 Z/Z IPL * 

CP SPOOL PUNCH CONT TO * 

PUNCH IPL IBCDASDI Z (NOH) 

PUNCH TEMP IBCDASDI * (NOH) 

CP SPOOL PUNCH NOCONT 

CP CLOSE PUNCH 

CP IPL OOC 

You execute this procedure by entering the filename of the EXEC: 

tempdisk 

When the final line of this EXEC is executed, the IBCDASDI program is in 
control. YOU must then signal an attention interruption using the 
Attention or Enter key, and you receive the message: 

IBC105A DEFINE INPUT DEVICE 

You should enter: 

input=25a0,00c 

to indicate that the control statements should be read from your card 
reader, which is a virtual 2540 device at virtual address OOC. 

When the IBCDASDI program is finished, your virtual machine is in the 
CP environment and must reload CMS (with the IPL command) to begin 
virtual machine execution. You can then access the temporary disk: 

ace 198 c 

and CMS responds: 

C(198) R/H - OS 
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Defining DOS Input and Output Files 

I I^ote; This information is for VSE/VSAH users. OS/VS VSAM users should 
refer to the section "Defining OS Input and Output Files." 

You must use the DLBL command to define VSAM input and output files for 
both the AMSERV command and for program execution. The operands 
required on the DLBL command are: 

dlbl ddname filemode DSN datasetname (options SYSxxx 

where "ddname" corresponds to the FILE parameter in the AMSERV file and 
"datasetname" corresponds to the entry name or filename of the VSAM 
file. 

There are several options you can use when issuing the DLBL command 
to define VSAM input and output files. These are: 

• VSAM, which you must use to indicate that the file is a VSAM file. 

Note: You do not have to use the VSAM option to identify a file as a 

VSAM file if you are using any of the other options listed here, 

since they imply that the file is a VSAM file. In addition, the 

ddnames (filenames) IJSYSCT and IJSYSDC also indicate that the file 
being defined is a VSAM file. 

• EXTENT, which you must use when you are defining a catalog or a VSAM 
data space; you are prompted to enter the volume information. This 
option effectively provides the function of the EXTENT card in 
DOS/VS. 

• MOLT, Which you must use in order to access a multivolume VSAM file; 
you are prompted to enter the extent information. 

• CAT, which you can use to identify a catalog which contains the entry 
for the VSAM file you are defining- 

• BOFSP, which you can use to specify the size of the buffers VSAM 
should use during program execution. 

Options are entered following the open parenthesis on the DLBL command 
line, with the SYSxxx: 

assgn sysOOS e 

dlbl filel b1 dsn workfile (extent cat cat2 sysOOS 

Additional examples using some of these options are shown below. 



USING VSAM CATALOGS 

While you are developing and testing your VSAM programs in CMS, you may 
find it convenient to create and use your own master catalog, which may 
be on a CMS minidisk. VSAM catalogs, like any other cluster, can be 
shared read-only among several users- 

You name the VSAM master catalog for your terminal session using the 
logical unit SYSCAT in the ASSGN command and the ddname IJSYSCT for the 
DLBL command. For example, if your VSAM master catalog is located on a 
DOS disk you have accessed as a C-disk, you would enter: 
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assgn syscat c 

dlbl ijsysct c dsn mastcat (syscat 

Note; When you use the ddname IJSYSCT you do 
VSAH option on the DLBL command. 



not need to specify the 



You must identify the master catalog at the start of every terminal 
session. If you are always using the same master catalog, you might 
include the ASSGN and DLBL commands in an EXEC procedure or in your 
PROFILE EXEC. You could also include the commands necessary to access 
the DOS system residence volume and enter the CHS/DOS environment: 

ACCESS 350 Z 

SET DOS ON Z (VSAM 

ACCESS 555 C 

ASSGN SYSCAT C 

DLBL IJSYSCT C DSN MASTCAT (SYSCAT PERM 

YOU should use the PERM option so that you do not have to reset the 
master catalog assignment after clearing previous DLBL definitions. 

You must use the VSAH option on the SET DOS ON command line if you 
want to use any access method services function or access VSAH files. 

Defining a Master Catalog 

The sample ASSGN and DLBL commands used in the above EXEC are almost 
identical with those you issue to define a master catalog using AHSERV. 
The only difference is that you must enter the EXTENT option so that you 
can list the data spaces that this master catalog is to control. 

As an example, suppose that you have a 30-cylinder 3330 minidisk 
assigned to you to use for testing your VSAM programs under CHS. 
Assuming that the minidisk is in your directory at address 333, you 
should first access it: 

access 333 d 
D (333) R/W - OS 



If you formatted the minidisk yourself, you know what its label is. 
not, you can find out what the label is by using the CMS command: 

query search 

The response might be: 



If 



0SR191 


191 


A 


R/H 


DOS333 


333 


C 


R/W 


SYS190 


190 


s 


R/O 


SYS19E 


19E 


Y/S 


R/O 



- OS 



Ose the label DOS333 in the VOLUMES parameter in the MASTCAT AHSERV 
file: 

DEFINE MASTERCATALOG - 
(NAME (MASTCAT ) - 
VOLUME (DOS333) - 
CYL (4) - 
FILE (IJSYSCT) ) 

Now, to find out what extents on the minidisk you can allocate for VSAM, 
use the LISTDS command with the EXTENT option: 
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listds d (free 

The response from LISTDS might look like this: 

FREESPACE INFORMATION FOR 'D» DISK: 
CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 01 1 000 09 9 9 
000 11 11 029 18 569 560 

From this response, you can see that the volume table of contents (VTOC) 
is located on the first cylinder, so you can allocate cylinders 1 
through 29 for VSAM: 

assgn syscat c 

dlbl ijsysct c dsn mastcat (syscat perm extent 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

19 551 

(null line) 

After entering the extents, in tracks, giving the relative track number 
of the first track to be allocated followed by the number of tracks, you 
must enter a null line to complete the command- A null line is required 
because, when you enter multiple extents, entries may be placed on more 
than one line. If you do not enter a null line, the next line you enter 
causes an error, and you must re-enter all of the extent information. 

Note that, as in DOS/VS, the extents must be on cylinder boundaries, and 
you cannot allocate cylinder 0. 

Now you can issue the AMSERV command: 

amserv mastcat 

A ready message with no return code indicates that the master catalog is 

defined. You do not need to reissue the ASSGN and DLBL commands in order (^ 

to use the master catalog for additional AMSERV functions. "i 



JSefinijia User Catalogs 

You can use the AMSERV command to define private catalogs and spaces for 
them, also. The procedures for determining what space you can allocate 
are the same as those outlined in the example of defining a master 
catalog. 

For a user catalog, you may use any programmer logical unit, and any 
ddname: 

access 199 e 
listds e (free 



assgn sysOOl e 

dlbl cati e dsn private cati (sysOOl extent perm 



amserv usercat 



^ 
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The file USERCAT AMSERV might contain the following: 

DEFINE DSERCATALOG - 

(NAME (PRIVATE. CAT1) - 
FILE (IJSYSUC) - 
CYL (4) - 
VOLUME (D0SVS2) - 
CATALOG (MASTCAT) ) 

After this AMSERV command has completed successfully you can use the 
catalog PRIVATE. CAT1 . When you issue a DLBL command to identify a 
cluster or data set cataloged in this catalog, you must identify the 
catalog using the CAT option on the DLBL command for the file: 

assgn syslOO c 

dlbl file2 e dsn ? (syslOO cat cati 

Or, you can define this catalog as a job catalog. 



^sin^ a Job Catalog 

If you want to set up a user catalog as a job catalog so that it will be 
searched during all subsequent jobs, you can define the catalog using 
the special ddname IJSYSDC. For example: 

assgn syslOI c 

dlbl ijsysuc c dsn private cat1 (sys101 perm 

If you defined a user catalog (IJSYSDC) for a terminal session and 
you use the AMSERV command to access a VSAM file, the user catalog takes 
precedence over the master catalog. This means that for files that 
already exist, only the user catalog is searched. When you define a 
cluster, it is cataloged in the user catalog, rather than in the master 
catalog, unless you use the CAT option to override it. 

If you want to use additional catalogs during a terminal session, you 
first define them just as you would any other VSAM file: 

assgn sysOlO f 

dlbl mycat2 f dsn private cat2 (sysOlO vsam 

Then, when you enter the DLBL command for the VSAM file that is 
cataloged in PRIVATE. CAT2 use the CAT option to refer to the ddname of 
the catalog: 

assgn sysOII f 

dlbl input f dsn input file (sysOU cat mycat2 

If you want to stop using a job catalog defined as IJSYSDC, you can 
clear it using the CLEAR option of the DLBL command: 

dlbl ijsysuc clear 

Then, the master catalog becomes the job catalog for files not defined 
with the CAT option. 
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Catalog Passwords 

When you define passwords for VSAM catalogs in CMS, or when you use CMS 

to access VSAM catalogs that have passwords associated with them, you { 

must supply the password from your terminal when the AMSERV command 

executes. The message that you receive to prompt you for the password 

is the same message you receive when you execute access method services: 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV FILE catalog 

When you enter the proper password, AMSERV continues execution. 



DEFINING AND ALLOCATING SPACE FOR VSAM FILES 

You can use CMS AMSERV to allocate additional data spaces for VSAM. To 
use the DEFINE SPACE control statement, you must have defined the 
catalog that is to control the space, and you must have the volume or 
volumes on which the space is to be allocated mounted and accessed. 

For example, suppose you have a DOS-formatted 3330 disk attached to 
your virtual machine at virtual address 255. After accessing the disX 
and determining the free space on it, you could create a file named 
SPACE AMSERV: 

DEFINE SPACE - 

(FILE (FILE1) - 
TRACKS (1900) - 
VOLUME (123456) - 
CATALOG (PRIVATE,.CAT2 CAT2) ) 

To execute this AMSERV file, define PRIVATE. CAT2 as a user catalog using 
the ddname CAT2, and then define the ddname for the FILE parameter: 

access 255 c 

assgn sysOlO c 

dlbl cat2 c dsn private cat2 (sysOlO vsam 

assgn sysOII c 

dlbl filel c (extent sysOII cat cat2 

Note that you do not need to enter a data set name to define the space. 
When CMS prompts you for the extents of the space you can enter the 
extent specifications: 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
190 1900 



When you define space for VSAM, you should be sure that the VOLUMES 
parameter and the space allocation parameter (whether CYLINDER, TRACKS, 
or RECORDS) in the AMSERV file agrees with the information you provide 
in the DLBL command. All data extents must begin and end on cylinder 
boundaries. Any additional space you provide in the extent information 
that is beyond what you specified in the AMSERV file is claimed by VSAM. 



i 
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Hhen you are specifying extents for a master catalog, data space, or 
unique file, you can specify up to 16 extents on a volume for a 
particular space. When prompted by CMS to enter the extents, you must 
separate different extents by commas or place them on different lines. 
To specify a range of extents in the above example, you can enter: 

dlbl filel c (extent sysOU 
190 190, 570 190, 1900 1520 
(null line) 

— or — 

dlbl filel c (extent sysOII 
190 190 
570 190 
1900 1520 

(null line) 

Again, the first number entered for each extent represents the relative 
track for the beginning of the extent and the second number indicates 
the number of tracks. 

Sp^cif^in^ Multivolume Extents 

You can define spaces that span up to nine volumes for VSAM files; all 
of the volumes must be accessed and assigned when you issue the DLBL 
command to define or identify the data space. 

You should remember, though, that if you are using AMSEBV and you do 
not use the PRINT option, you must have a read/write CMS disk so that 
AMSERV can write the output LISTING file. 

If you are defining a new multivolume data space or unique cluster, 
you must specify the extents on each volume that the data is to occupy 
(starting track and number of tracks) , followed by the disk mode letter 
at which the disk is accessed and the programmer logical unit to which 
the disk is assigned: 



access 


135 b 


access 


136 c 


access 


137 d 


assgn 


sysOOl 


assgn 


sys002 


assgn 


sys003 



b 

c 
d 
dlbl newfile b (extent sysOOl 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
100 60 b sysOOl, 400 80 b sysOOl, 60 HO d sys003 
2000 100 c sys002 
(null line) 

If you specify more than one extent on the same line, the extents must 
be separated by commas; if you enter a comma at the end of a line, it is 
ignored. Different extents for the same volume must be entered 
consecutively. 

Note that in the preceding example, the extent information is for 
231U disks; and that these extents are also on cylinder boundaries. 

When you enter multivolume extents you can use a default mode. For 
example: 
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dlbl newfile b (extent sysOOl 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
100 60, aOO 80, 60 40 d sys003, 
2000 100 c sys002 
(null line) 

Any extents you enter without specifying a mode letter and SYSxxx value 
default to the mode and SYSxxx on the DLBL command line, in this case, 
the B-disk, SYSOOI. 

If you make any errors issuing the DLEL command or extent 
information, you must re-enter the entire command sequence. 

IDENTIFYING EXISTING MULTIVOLDME FILES: When you issue a DLBL command to 
identify an existing multivolume ?SAM file, you must use the MDLT option 
of the DLBL command: 

dlbl old b1 dsn ? (sys002 mult 

DMSDLB220R ENTER DATA SET NAME: 

dostest.file 

DMSDLB330R ENTER VOLUME SPECIFICATIONS: 

c sys004, d sys003 

e sysOO? 

(null line) 

When you enter the DLBL command you should specify the mode letter and 
logical unit for the first volume on the command line. When you enter 
the MDLT option you are prompted to enter additional specifications for 
the remaining extents. In the preceding example, the data set has 
extents on disks accessed as B-, C-, D-, and E-disks. 

USING TAPE INPUT AND OUTPUT 

If you are using AMSERV for a function that requires tape input and/or 
output, you must have the tape(s) attached to your virtual machine. The 
valid addresses for tapes are 181, 182, 183, and 184. When referring to 
tapes, you can also refer to them using their CMS symbolic names TAPl, 
TAP2, TAP3, and TAP4. 

For AMSERV functions that use tape input/output, the TLBL control 
statement is simulated by building a dummy DLBL containing a 
user-supplied ddname (filename) . CMS does not read tape labels and does 
not recognize tape data set names. 

When you invoke the AMSERV command, you must use the TAPIN or TAPOUT 
option to specify the tape device being used: 

amserv export (tapout 181 

In this example, the output from the AMSERV control statements in a file 
named EXPORT goes to a tape at virtual address 181. CMS prompts you to 
enter the ddname: 

DMSAMS367R ENTER TAPE OUTPUT DDNAMES: 

After you enter the ddname specified on the FILE parameter in the AMSERV 
file and press the carriage return, the AMSERV command executes. 

AMSERV opens all tape files as standard labelled tapes (FILAB=STD on 
the DTFMT macro) . Therefore, you need a LABELDIF command for any tape 
file used for input or output with AMSERV. The LABELDEF command is the 
CMS/DOS equivalent of the DOS/VSE TLB control statement. The LABELDEF 
command is used to specify information in V0L1 and HDRl labels on the 
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tape- See the description of the LABELDEF command in section 7 for more 
information on this command. 

You should use the same name for the filename on your LABELDEF 
command as you do for the ddname you enter in reply to message 
DMSAMS367R (the ddname specified on the FILE parameter in the AMSEBV 
file). However, the LABELDEF command must be issued before the AMSERV 
command. The following sequence of commands might be used when you have 
tape output: 

assgn sysOOS tap1 

tape rew (181 

assgn syscat e 

assgn sys006 e 

labeldef catout fid catfile volid amserv 

dlbl ijsysct e dsn mastcat (syscat vsam 

dlbl catin e dsn file (sys006 vsam 

amserv repro (tapout 181 

DMSAMS367R ENTER TAPE OUTPUT DDNAMES 

catout 

Note that if you do not care what is written in a tape output label 
or do not want input labels checked, you can specify a LABELDEF with no 
parameters other than filename. The command: 

labeldef intape 

used for an input tape with ddname INTAPE causes the standard labels on 
the tape to be skipped without any checking. A similar statement for 
output writes tape labels with default values (see the description of 
the LABELDEF command in section 7) . 

If you try to use a tape that does not already contain a VOLl label 

for an AMSERV tape file, you will receive an error message. If the tape 

is used for output, this message is followed by another message that 

informs you that you have a choice of continuing by writing a VOLl label 

on the previously unlabelled tape or rejecting this tape. Input tape 

files must already contain standard VOLl and HDR1 labels to be processed 
by AMSERV. 
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Ks^dina VSAM Ta£e Files 

When you create a tape in CMS using AMSERV, CMS writes a tape mark 
preceding each output file that it writes. When this same tape is read 
using AMSERV under CMS, HDR1 and V0L1 labels are checked using the 
LABELDEF command you provide. If you read this tape in a real DOS/VS 
system, you should use a TLBL card instead of the LABELDEF command. 

Similarly, when you create a tape under a DOS/VS system using access 
method services, if the tape is created with standard labels, CMS AMSEHV 
has no difficulty reading it. 

The only time you should worry about positioning a tape created by 
AMSERV is when you want to read the tape using a method other than 
AMSERV, for example, the MOVEFILE command. Then, you must forward space 
the tape past the label, using the CMS TAPE command before you can read 
it. 



Defining OS Input and Output Files 

I Note; This information is for OS/VS VSAM users only. VSE/VSAM users 
should refer to "Defining DOS Input and Output Files" for information on 
defining files for use with VSAM. 

If you are going to use access method services to manipulate VSAM or SAM 
files or you are going to execute VSAM programs under CMS, you must use 
the DLBL command to define the input and output files. The basic format 
of the DLBL command is: 

DLBL ddname filemode DSN datasetname (options 

where ddname corresponds to the FILE parameter in the AMSERV file and 

datasetname corresponds to the entry name of the VSAM file, that is, the 

name specified in the NAME parameter of an access method services 
control statement. 

If you are using a CMS file for AMSERV input or output, use the CMS 
operand and enter CMS file identifiers as follows: 

dlbl mine a cms out file1 (vsam 

The maximum length allowed for ddnames under CMS VSAM is seven 
characters. This means that if you have assigned eight-character ddnames 
(or filenames) to files in your programs, only the first seven 
characters of each ddname are used. So, if a program refers to the 
ddname ODTPDTDD, you should issue the DLBL command for a ddname of 
OOTPDTD. Since you can encounter problems with a program that contains 
ddnames with the same first seven characters, you should recompile those 
programs using seven-character ddnames. 

There are several options you can use when issuing the DLBL command 
to define VSAM input and output files. These are: 

• VSAM, which you must use to indicate that the file is a VSAM file. 

Note; YOU do not have to use the VSAM option to identify a file as a 

VSAM file if you are using any of the other options listed here, 

since they imply that the file is a VSAM file. In addition, the 

ddnames (filenames) IJSISCT and IJSYSDC also indicate that the file 
being defined is a VSAM file. 
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EXTENT, Which you Bust use when you are defining a catalog or a VSAM 
data space; you are prompted to enter the volume information. 

MOLT, which you must use in order to access a multivolume 7SAM file; 
you are prompted to enter the extent information. 

CAT, which you can use to identify a catalog which contains the entry 
for the VSAM file you are defining- 

BOFSP, which you can use to specify the size of the buffers VSAM 
should use during program execution. 



ALLOCATING EXTENTS ON OS DISKS AND MINIDISKS 

When you use access method services to manipulate VSAM files under OS, 
you do not have to worry about allocating the real cylinders and tracks 
to contain the files. When you use CMS AMSERV, however, you are 
responsible for indicating which cylinders and tracks should contain 
particular VSAM spaces when you use the DEFINE control statement to 
define space. 

Extents for VSAM data spaces can be defined, in AMSERV files, in 
terms of cylinders, tracks, or records. Extent information you supply to 
CMS when executing AMSERV must always be in terms of tracks. When you 
define data spaces or unique clusters, the extent information (number of 
cylinders, tracks, or records) in the AMSERV file must match the extents 
you supply when you issue the DLBL command to define the file. When you 
supply extent information for the master catalog, any extents you enter 
in excess of those required for the catalog are claimed by the catalog 
and used as data space. 

CMS does not make secondary space allocation for VSAM data spaces. 
If you execute an AMSERV file that specifies a secondary space 
allocation, CMS ignores the parameter. 

When you use the DLBL command to define VSAM data space, you must use 
the EXTENT option, which indicates to CMS that you are going to enter 
data extents. For example, if you enter: 

dlbl space b (extent 

CMS prompts you to enter the extents: 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

When you enter the extents, you specify the relative track number of the 
first track of the extent, followed by the number of tracks. For 
example, if you are allocating an entire 2314 disk, you would enter: 

20 3980 

(null line) 

lou can never write on cylinder 0, track 0; and, since VSAM data 
spaces must be allocated on cylinder boundaries, you should never 
allocate cylinder 0. Cylinder is often used for the volume table of 
contents (VTOC) as well, so it is always best to begin defining space 
with cylinder 1. 

The list below shows the DASD devices supported by CMS VSAM, the 
number of cylinders on each that can be allocated for VSAM space, and 
the number of tracks per cylinder: 
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Disk 

2314/2319 
3330 Model 


1 


Cylinders 
200 
404 


Tracks^Cj^linder 
20" 
19 


3330 Model 


11 


808 


19 


3340 Model 


35 


348 


12 


3340 Model 


70 


696 


12 


3350 




555 


30 



You can determine which disk extents on an OS disk or minidisk are 
available for allocation by using the LISTDS command with the FHEE 
option, which also indicates the relative track numbers, as well as 
actual cylinder and head numbers. 



USING VSAM CATALOGS 

While you are developing and testing your VSAM programs in CMS, you may 
find it convenient to create and use your own master catalog, which may 
be on a CMS minidisk. VSAM catalogs, like any other cluster, can be 
shared read-only among several users. 

You name the VSAM master catalog for your terminal session using the 

ddname IJSYSCT for the DLBL command. For example, if your VSAM master 

catalog is located on an OS disk you have accessed as a C-disk, you 
would enter: 

dlbl ijsysct c dsn master catalog (perm 

You must define the master catalog at the start of every terminal 
session. If you are always using the same master catalog, you might 
include the DLBL command you need to define it in your PROFILE EXEC: 

ACCESS 555 C 

DLBL IJSYSCT C DSN MASTCAT (PERM 

You should use the PERM option so that you do not have to reset the 
master catalog assignment after clearing previous DLBL definitions- The 
command: 

dlbl * clear 

clears all file definitions except those entered with the PERM option. 



Defining a Master Catalog 

The sample DLBL command used in the preceding example is almost 
identical with the one you would issue to define a master catalog using 
AMSERV. The only difference is that you must enter the EXTENT option so 
that you can list the data spaces that this master catalog is to 
control. 

As an example, suppose that you have a 30-cylinder 3330 minidisk 
assigned to you to use for testing your VSAM programs under CMS. 
Assuming that the minidisk is in your directory at address 333, you 
should first access it: 

access 333 d 
D (333) R/W - OS 
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If you formatted the minidisk yourself, you know what label you assigned 
it; if not, you can find out the label assigned to the disk by issuing 
the CMS command: 

query search 

The response might be: 

0SR191 191 A R/W 

VSAM03 333 C R/W - OS 

SYS109 190 S R/0 

SYS19E 19E Y/S R/0 

Ose the volume label VSAM03 in the MASTCAT AMSERV file: 

DEFINE MASTERCATALOG - 
(NAME (MASTCAT ) - 
VOLUME (7SAM03) - 
CYL (4) - 
FILE (IJSYSCT) ) 

To find out what extents on this minidisk you can allocate for VSAM, use 
the LISTDS command with the FREE option: 

listds d (free 

The response from LISTDS might look like this: 

FREESPACE INFORMATION FOR 'D* DISK: 
CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 01 1 000 09 9 9 
000 11 11 029 18 569 560 

From this response, you can see that the VTOC is located on the first 
cylinder, so you can allocate cylinders 1 through 29 for VSAM: 

dlbl ijsysct c dsn mastcat (perm extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 551 

(null line) 

After entering the extents, in tracks, giving the relative track number 
of the first track to be allocated followed by the number of tracks, you 
must enter a null line to complete the command. (A null line is required 
because, when you enter multiple extents, entries may te placed on more 
than one line.) 

Now you can issue the AMSERV command: 

amserv mastcat 

A Ready message with no return code indicates that the master catalog is 
defined. You do not need to reissue the DLBL command in order to 
identify the master catalog for additional AMSERV functions. 



^ef inina User Catalogs 

You can use the AMSERV command to define private catalogs and spaces for 
them. The procedures for determining what space you can allocate are the 
same as those outlined in the example of defining a master catalog. 

To define a user catalog, you can assign any ddname you want: '^ 
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access 199 e 
listds e (free 



dlbl cat1 e dsn private cati (extent 

amserv usercat 

The file OSERCAT AMSERV might contain the following: 

DEFIN^ USERCATALOG - 

(NAME (PRIVATE. CATI) - 
FILE (CATI) - 
CYL (U) - 
VOLUME (OSVSAM) - 
CATALOG (MASTCAT) ) 

After this AMSERV command has completed successfully you can use the 
catalog PRIVATE. CAT1. When you define a file cataloged in it, you 
identify it using the CAT option on the DLBL command: 

dlbl file2 c dsn ? (cat cati 

Or, you can define it as a job catalog. 

Ds in q a Job Catalog 

During a terminal session, you may be referencing the same private 
p catalog many times. If this is the case, you can identify a job catalog 
by using the ddname IJSYSDC. Then, that catalog is searched during all 
subseguent jobs, unless you override it using the CAT option when you 
use the DLBL command to define a file. 

If you defined a user catalog (IJSYSOC) for a terminal session and 
you use the AMSERV command to access a VSAM file, the user catalog takes 
precedence over the master catalog. This means that for files that 
already exist, the job catalog is searched. When you define a cluster, 
it is cataloged in the job catalog, rather than in the master catalog, 
unless you use the CAT option to override it. CMS never searches more 
than one VSAM catalog. 

You should use the CAT option to name a catalog when the AMSERV file 
you are executing references, with the CATALOG parameter, a catalog that 
is not defined either as the master catalog or as a user catalog. 

If you want to use additional catalogs during a terminal session, you 
first define them just as you would any other VSAM file: 

dlbl mycat2 f dsn private cat2 (vsam 

Then, when you enter the DLBL command for the VSAM file that is 
cataloged in PRIVATE. CAT2 use the CAT option to refer to the ddname of 
the catalog: 

dlbl input f dsn input file (cat mycat2 

If you want to stop using a job catalog defined with the ddname IJSYSUC, 
you can clear it using the CLEAR option of the DLBL command: 



\ 



/ 
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dlbl ijsysuc clear 

or, you can assign the ddname IJSYSUC to some other catalog. If you 
clear the ddname for IJSYSUC, then the master catalog becomes the job 
catalog. 



Catalog Passwords 

When you define passwords for YSAM catalogs in CMS, or when you use CMS 
to access VSAM catalogs that have passwords associated with them, you 
must supply the password from your terminal when the AMSERV command 
executes. The message that you receive to prompt you for the password 
is the same message you receive when you execute access method services: 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV FILE catalog 

When you enter the proper password, AMSERV continues execution. 



DEFINING AND ALLOCATING SPACE FOR VSAM FILES 

You can use CMS AMSERV to allocate additional data spaces for VSAM. To 
use the DEFINE SPACE control statement, you must have defined either the 
master catalog or a user catalog which will control the space, and you 
must have the volume or volumes on which the space is to be allocated 
mounted and accessed. 

For example, suppose you have an OS 3330 disk attached to your 
virtual machine at virtual address 255. After accessing the disk and ( 
determining the free space on it, you could create a file named SPACE 
AMSERV: 

DEFINE SPACE - 

(FILE (FILE1) - 
TRACKS (1900) - 
VOLUME (123456) - 
CATALOG (PRIVATE. CAT2 CAT2) ) 

To execute this AMSERV file, you must define PRIVATE. CAT2 using the 
ddname CAT2, and then define the ddname for the file: 

access 255 c 

dlbl cat2 c dsn private cat2 (vsam 

dlbl filel c (extent cat cat2 

You do not need to enter a data set name to define the space. When CMS 
prompts you for the extents of the space, you can enter the extent 
specifications: 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
190 1900 



When you define space for VSAM, you should be sure that the VOLUMES 
parameter and the space allocation parameter (whether CYLINDER, TRACKS, 
or RECORDS) in the AMSERV file agree with the track information you 
provide in the DLBL command. 
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Specifying Multiple Extents 

When you are specifying extents for a master catalog, data space, or 
unique file, you can specify up to 16 extents on a volume for a 
particular space. When prompted by CMS for the extents, you must 
separate the different extents by commas, or place them on different 
lines. TO specify a range of extents in the above example, you could 
enter: 

dlbl filel c (extent 
190 190, 570 190, 1900 1520 
(null line) 

— or — 

dlbl filel c (extent 
190 190 
570 190 
1900 1520 

(null line) 

Again, the first number entered for each extent represents the relative 
track for the beginning of the extent and the second number indicates 
the number of tracks. 



Specifying M u 1 t i v olume Ex te n t s 

You can define spaces that span up to nine volumes for VSAM files; all 
of the volumes must be accessed and assigned «hen you issue the DLEL 
command to define or identify the data space. 

You should remember, though, that if you are using AMSERV and you do 
not use the PRINT option, you must have a read/write CMS disk so that 
AMSERV can write the output LISTING file. 

If you are defining a new multivolume data space or unique cluster, 
you must specify the extents on each volume that the data is to occupy 
(starting track and number of tracks), followed by the disk mode letter 
at which the disk is assigned: 

access 135 b 

access 136 c 

access 137 d 

dlbl newfile b (extent 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

100 60 b, 400 80 b, 60 40 d , 

2000 100 c 

(null line) 

If you enter more than one extent on the same line, the extents must be 
separated by commas; if you enter a comma at the end of a line, it is 
ignored. Different extents for the same volume must be entered 
consecutively. Note that in this example, the extent information is for 
2314 disks and that these extents are also on cylinder boundaries. 

When you enter multivolume extents, you do not have to enter a mode 
letter for those extents on the disk identified in the DLBL command. 
For the extents on disk B in the above example, you could enter: 
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dlbl newfile b (extent 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

100 400 80, 60, 60 40 d 

2000 100 c 

(null line) 

If you make any errors issuing the DLBL command or extent 
information, you must re-enter the entire cpmmand sequence. 

IDENTIFYING EXISTING MOLTIVOLDME FILES: When you issue a DLBL command to 
identify an existing multivolume VSAM file, you must use the HOLT option 
of the DLBL command sequence: 

dlbl old b1 dsn ? (mult 

DMSDLB220R ENTER DATASET NAME: 

vsamtest.file 

DMSDLB330R ENTER VOLUME SPECIFICATIONS: 

C, d 

e 

(null line) 

When you enter the DLBL command you should specify the mode letter for 
the first disk volume on the command line. When you enter the BOLT 
option you are prompted to enter additional specifications for the 
remaining extents. In the above example, the data set has extents on 
disks accessed as B-, C-, D-, and E-disks. 

USING TAPE INPUT AND OUTPUT 

If you are using AMSERV for a function that requires tape input and/or 
output, you must have the tape(s) attached to your virtual machine. The 
valid addresses for tapes are 181, 182, 183, and 184. When referring to 
tapes, you can also refer to them using their CHS symbolic names TAPl, 
TAP2, TAP3, and TAP4. 

When you use AMSERV to create or read a tape, you supply the ddname 
for the tape device interactively, after you issue the AMSERV command. 
You must also supply a LABELDEF command for tape label checking before 
you issue the AMSERV command. To indicate to AMSERV that you are using 
tape for input or output, you must use the TAPIN or TAPOOT option to 
specify the tape device being used: 

labeldef tapedd fid filename... 
amserv export (tapout 181 

In this example, the output from an EXPORT function is to a tape at 
virtual address 181. CMS prompts you to enter the ddname: 

DMSAMS367R ENTER TAPE OUTPUT DDNAMES: 

After you enter the ddname (TAPEDD in this example) for the tape file, 
AMSERV begins execution, 

AMSERV in CMS treats all tape files as having standard labels. The 
LABELDEF command is required because the CMS/DOS routine that performs 
the tape open needs label information for standard labelled tapes. See 
the description of the LABELDEF command in Section 7 for further 
information. The filename you specify on the LABELDEF command should be 
the same one you use to reply to the access method service message that 
requested you to supply the tape's ddnames. However, the LABELDEF 
command must be issued before the AMSERV command. If you only want the 
tape labels skipped, but not checked, enter a LABELDEF with no 
parameters other than filename- 
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Tapes ased for input nust always contain standard YOLI, HDR1, and 
E0F1 labels or they are rejected by CMS ABSER7. Output tapes do not 
need to contain V0L1 labels because the user is proipted to enter a 
volume serial number and have the V0L1 label written if he wants. 
However, blank tapes should not be used for output because the open 
routine tries to read the tape. 



Reading Tapes 

When you create a tape file using AHSERV under CHS, CHS writes a label 
file preceding each output data file. When CHS AHSERV is used to read 
this same file, it checks the HDR1 and V0L1 labels using the LABELDEF 
command you provide before it reads the data file. If you want to read 
the tape on a real OS/TS system, however, you must use the LABEL=SL as a 
parameter on the data definition (DD) card for the tape. 
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If you are creating a tape under OS/VS access method services to be 
read by CHS AHSERV, you must be sure to create the tape using standard 
labels so that CHS can read it properly. CHS will not be able to read a 
tape created with LABEL=(,NL) on the DD card. 

For CHS to read this tape for any other purpose (for example, to use 
the MOVEFILE command to copy it) , you must remember to forward space the 
file past the label file before beginning to read it. 



Using AMSERV under CMS 

This section provides examples of AHSERV functions executed under CHS. 
The examples are applicable to both the CMS (OS) and CMS/DCS 
environments. You should be familiar with the material presented in 
either "Defining DOS Input and Output Files" or "Defining OS Input and 
Output Files," depending on whether you are a DOS or an OS user, 
respectively. For the examples shown below, command lines and options 
that are required only for CHS/DOS users are shaded. OS users should 
ignore these shaded entries. 

A CMS format variable file cannot be used directly as input to AMSEEV 
functions as a variable (V) or variable blocked (VB) file because the 
standard variable CMS record does not contain the BL and RL headers 
needed by the variable record modules- If these headers are not included 
in the record, errors will result. 

All files placed on the CMS disk by AHSERV will show a RECFH of V, 
even if the true format is fixed (F) , fixed blocked (FB) , undefined (0) , 
variable or variable blocked. The programmer must know the true format 
of the file he is trying to use with the AMSERV command and access it 
properly or errors will result. 

A CMS standard variable-format file can be accessed as REcrM=D to use 
the file as follows: 

AMSERV AMREPUV 

The file AMREPOS AHSERV contains the following 2 cards: 

REPRO INFILE (INPUT ENV (RECFH (U) , BLKSZ (800) ,PDEV (3330) ) ) 

OOTFILE (OUTPOT EHV (RECFH (V) , BLKSZ (800) ,RECSZ (84) ,PDEV (3330) ) ) 

The input file can be any CMS file with LEECL 800 or less. The 
output file will be a true variable file that can be used with AMSERV. 



USING THE DEFINE AND DELETE FUNCTIONS 



When you use the DEFINE and DELETE control statements of AHSERV, you do 
not need to specify the DSN parameter on the DLBL command: 

dlbl ijsysct c (perm extent «yaca,t 

If the above commands are executed prior to an AMSERV command to define 
a master catalog, the DEFINE will be successful as long as you have 
assigned a data set name using the NAHE parameter in the AHSERV file. 
p The same is true when you define clusters, or when you use the DELETE 
function to delete a cluster, space, or catalog. 
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When you do not specify a data set name, AHSEBV obtains the naoe froB 
the AHSERV file. In the case of defining or deleting space, no data set 
name is needed; the FILE parameter corresponding to the ddname is all 
that is necessary, and AHSERV assigns a default data set name to the 
space. 

Rhen you define space on a minidisk using AHSERV, CHS does not check 
the extents you specify to see whether they are greater than the number 
of cylinders available. As long as the starting cylinder is a valid 
cylinder number and the extents you specify are on cylinder boundaries, 
the DEFINE function completes successfully. However, you receive an 
error message when you use an AHSERV function that tries to use this 
space. 



^SjUn^M a Suballocated Cluster 

TO define a cluster for VSAH space that has already been allocated, you 
need (1) an AHSERV file containing the control statements necessary for 
defining the cluster, and (2) the master catalog (and, perhaps, user 
catalog) volume, which will point to the cluster. The volume on which 
the cluster is to reside does not have to be online when you define a 
suballocated cluster. 

For example, the file CLUSTER AHSERV contains the following: 

DEFINE CLUSTER ( NAHE (BOOK. LIST) - 

VOLUMES (123456) - 

TRACKS (UO) - 

FILE (BOOK) - 

KEYS (14,0) RECORDSIZE (120,132) ) - 
DATA (NAHE (BOOK. LIST. DATA) ) - 
INDEX (NAME (BOOK. LIST. INDEX) ) 

To execute this file, you would need to enter the following command 
sequence (assuming that the master catalog, on volume 123U56, is in your 
virtual machine at address 310) : 

access 310 b 



dlbl ijsysct b (perm 
amserv cluster 

Note that to define a suballocated cluster, you do not need to provide a 
DLBL command to define it to AHSERV. 



JD^f ininc[ a Onijgue Cluster 

For a unique cluster (one defined with the UNIQUE attribute) , you must 
define the space for the cluster at the same time you define its name 
and attributes; thus the volume or volumes on which the cluster is to 
reside must be mounted and accessed when you execute the AHSERV command. 
YOU must supply extent information for the cluster's data and index 
portions separately. 

To execute an AHSERV file named UNIQUE which contains the following 
(the ellipses indicate that the AHSERV file is not complete): 
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DEFINE CLUSTER - 

(NAME (PAYROLL) ) - 
DATA ( FILE (ODATA) - 
UNIQUE - 

VOLUMES (567890) - 
CYLINDERS (40) - 

-.. ) - 

INDEX ( FILE (UINDEX) ) - 
UNIQUE - 

VOLUMES (567890) - 
CYLINDERS (10) - 
... ) 

the command sequence should be: 

access 350 c ^ 

dlbl udata c (extent ik^0$]^ 

DMSDLB331R ENTER EXTENT SPECIFICATIONS; 

800 800 c |^#004 

dlbl uindex c (extent 

600 200 c 

amserv unique 



Deleting Clusters, Sjgaces, and Catalogs 

When you use AMSERV to delete a VSAM cluster, the volume containing the 
cluster does not have to be accessed unless the volume also contains the 
catalog in which the cluster is defined. In the case of data spaces and 
user catalogs or the master catalog, however, the volume (s) must be 
mounted and accessed in order to delete the space. 

When you delete a cluster or a catalog, you do not need to use the 
DLBL command, except to define the master catalog; AMSERV can obtain the 
necessary file information from the AMSERV file. In the case of data 
spaces, you must supply a ddname (filename) with the DLBL command, but 
you do not need to use the DSN parameter. 

You should be particularly careful when you are using temporary disks 
with AMSERV, that you have not cataloged a temporary data space or 
cluster in a permanent catalog. You will not be able to delete the space 
or cluster from the catalog. 



USING THE REPRO, IMPORT, AND EXPORT (OR EXPORTRA/IMPORTRA) FUNCTIONS 

You can manipulate VSAM files in CMS with the REPRO, IMPORT, and EXPORT 
functions of AMSERV. You can create VSAM files from sequential tape or 
disk files (on OS, DOS, or CMS disks) using the REPRO function. Using 
REPRO, you can also copy VSAM files into CMS disk files or onto tapes. 
For the IMPORT/EXPORT process, you have the option (for smaller files) 
of exporting VSAM files to CMS disks, as well as to tapes. 

You cannot, however, use the EXPORT function to write files onto OS 

or DOS disks. Nor can you use the REPRO function to copy ISAM (indexed 

I sequential) files into VSAM data sets, since CMS cannot read ISAM files. 

I When creating a VSAM file from a non-VSAM disk file, the device track 
I size must be the maximum BLOCKSIZE in the INFILE statement. AMSERV 
I expects a DOS or OS file as input and will not open a disk file when the 
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BLOCKSIZE specified is greater than the track capacity of the disk 
device being used. 

You cannot use the ERASE or PURGE options of the EXPORT command if 
you are exporting a VSAM file from a read-only disk. The export 
operation succeeds, but the listing indicates an error code 184, meaning 
that the erase function could not be performed. 

You should not use an EXPORT DISCONNECT function from a CHS minidisk 
and try to perform an IMPORT CONNECT function for that data set onto an 
OS system,- OS incorrectly rebuilds the data set control block (DSCB) 
that indicates how much space is available. 

The AMSERV file below gives an example of using the REPRO function to 
copy a CMS seguential file into a VSAM file. The CMS input file must be 
sorted in alphameric sequence before it can be copied into the VSAM 
file, which is a keyed sequential data set (KSES) . The VSAM cluster, 
NAME. LIST, is defined in an AMSERV file named PAYROLL: 

DEFINE CLUSTER ( NAME (NAME. LIST ) - 

VOLUMES (CMSDEV) - 

TRACKS (20) - 

FILE (BOOK) - 

KEYS (14,0) - 

RECORDSIZE (120,132) ) - 
DATA (NAME (NAME. LIST. DATA) ) - 
INDEX (NAME (NAME. LIST. INDEX ) ) 

To sort the CMS file, create the cluster and copy the CMS file into it, 
use the following commands: 

sort name list a name sort a 
DMSSRieOUR ENTER SORT FIELDS: 

1 m 

access 135 c 

dlbl i jsysct c (perm 
amserv payroll 



dlbl sort a cms name sort 

ms3^g»- «(|s007--. <? 

dlbl name c dsn name list (sfBfi07 vsam 

amserv repro 

The file REPRO AMSERV contains: 

REPRO INFILE ( SORT - 

ENV (RECORDFORMAT (F) - 
BLOCKSIZE (80) - 
PDEV (3330) ) ) - 
OUTFILE (NAME) 

When you use the REPRO, IMPORT, or EXPORT functions with tape files, 
you must remember to use the TAPIN and TAPOUT options of the AMSERV 
command. These options perform two functions: they allow you to specify 
the device address of the tape, and they notify AMSERV to prompt you to 
enter a ddname. 

In the example below, a VSAM file is being exported to a tape. The 
file, TEXPORT AMSERV, contains: 

EXPORT NAME. LIST - 

INFILE (NAME) - 

OUTFILE (TAPE ENV (PDEV (2400) ) ) 
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To execute this AMSERV, you enter the commands as follows: 



dlbl name c (SfS0O$ vsam 

labeldef tape fid tapf volid deptIO exdte 790U0 

amserv texport (tapout 181 

DMSAMS367R ENTER TAPE OUTPUT DDNAMES: 

tape 

The fid, volid, and exdte parameters on LABELDEF are only examples; 
you can substitute any value you want for them on your tape label. 



WRITING EXECS FOR AMSERV AND VSAM 

You may find it convenient to use EXEC procedures for most of your 
AMSERV functions, as well as setting up input and output files for 
program execution, and executing your VSAM programs- If, for example, a 
particular AMSERV function reguires several disks and a number of DLEL 
statements, you can place all of the reguired commands in an EXEC file. 
For example, if the file below is named SETUP EXEC: 

ACCESS 135 B 
ACCESS 136 C 
ACCESS 137 D 
ACCESS 300 G 

DLBL IJSYSCT G (PERM SlSCht 

kSSm SYS001 B 

DLBL FILE1 B DSN FIRST FILE (VSAM StSOOl 

tBsm sTsmi c 

DLBL FILE2 C DSN SECOND FILE (VSAM SfSOOa 

As#0» sfsooa s. 

DLBL FILE3 D DSN THIRD FILE (VSAM SfS0d3 
AMSERV MULTFILE 

to invoke this seguence of commands, all you have to enter is the name 
of the EXEC: 

setup 

If you place, at the beginning of the EXEC file, the EXEC control 
statement: 

SERROR SEXIT SRETCODE 

then, you can be sure that the AMSERV command does not execute unless 
all of the prior commands completed successfully. 

For those AMSERV functions that issue response messages, you can use 
the &STACK EXEC control statement. For example: 

&ERROR SEXIT SRETCODE 

ACCESS 305 D 

%BBm StS007 D 

DLBL OUTPUT D (VSAM SfSOOT 

LABELDEF TAPE FID FILEl 

SERROR SCONTINUE 

SSTACK TAPE 

AMSERV TIMPORT (TAPIN 181 

SIF SRETCODE NE TYPE TIMPORT LISTING 

TAPE REW 

SEXIT 
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When the AMSERV command in the EXEC is executed, the request for the 
tape ddname is satisfied immediately, by the response stacked with the 
SSTACK statement. 

If you are executing a command that accepts multiple response lines, 
you have to stack a null line as follows: 

SSTACK C SIS002, D StS003 

SSTACK 

DLBL MOLTFILE B (MOLT SfSOOl 

Note: You can use the SBEGSTACK control statement to stack a series of 
responses in an EXEC, but you must use SSTACK to stack a null line. 
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Section 11. How VM/370 Can Help You Debug 
Your Programs 



Debugging is a critical part of the progran development process. When 
you encounter problems executing application programs or when you want 
to test new lines of code, you can use a variety of CP and CHS debugging 
commands and techniques to examine your program while it is executing. 

You can interrupt the execution of a program to examine and change 
your general registers, storage areas, or control words such as the 
program status word (PSW) , and then continue execution. Also, you can 
trace the execution of a program closely, so you can see where branches 
are being taken and when supervisor calls or I/O interruptions occur. 

In many cases, you may never need to look at a dump of a program to 
identify a problem. 



Preparing to Debug 

Before beginning to debug a program, you should have a current program 
listing for reference. When you use VM/370 to debug a program, you can 
monitor program execution, instruction by instruction, so you must have 
an accurate list of instruction addresses and addresses of program 
storage areas. You can obtain a listing of your program by using the 
PRINT command to print the LISTING file created by the assembler or 
compiler. To determine the virtual storage locations of program entry 
points, use the LOAD MAP file created by the LOAD and INCLUDE commands. 
If you are a CMS/DOS user, use the linkage editor map produced by the 
DOSLKED command. 

If the program that you are debugging creates printed or punched 
output and you will be executing the program repeatedly, you may not 
wish all of the output printed or punched. You should place your 
printer or punch in a hold status, so that any files spooled to these 
devices are not released until you specifically request it: 

cp spool printer hold 
cp spool punch hold 

When you are finished debugging you can use the CP QUERY command to see 
what files are being held and then you can select which files you may 
want to purge or release. 



When a Program Abends 

The most common problem you might encounter is an abnormal termination 
resulting from a program interruption. When a program running in a CMS 
virtual machine abnormally terminates (abends) , you receive, at your 
terminal, the message: 

DMSITP141T exception EXCEPTION OCCURRED AT address IN ROUTINE name 

and your virtual machine is returned to the CMS environment. From the 
message you can determine the type of exception (program check, 
operation, specification, and so on) , and, often, the instruction 
address in your program at which the error occurred. 
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Sometimes this is enough information for you to correct the error in 
your source program, recompile it and attempt to execute it again. 

When this information does not immediately identify the problem in 
your program, you can begin debugging procedures using VM/370. To 
access your program's storage areas and registers you can enter the 
command: 

debug 

immediately after receiving the abend message. This command places your 
virtual machine in the debug environment. 

To check the contents of general registers through 15, issue the 
DEBUG subcommand: 

gpr 15 

If you want to look at only one register, enter: 

gpr 3 

You might also wish to check the program status word (PSW) . Ose the PSW 
subcommand: 

psw 

You can examine storage areas in your program using the X subcommand: 

X 201AC 20 

In this example, the subcommand requests a display of 20 bytes, 
beginning at location 201AC in your program. Oser programs executed in 
CMS are always loaded beginning at location X*2C000» unless you specify 
a different address on the LOAD or FETCH command. To identify the 
virtual address of any instruction in a program, you only need to add 
20000 to the hexadecimal instruction address. 



RESUMING EXECUTION AFTER A PROGRAM CHECK 

On occasion, you will be able to determine the cause of a program check 
and continue the execution of your program. There are DEBUG subcommands 
you can use to alter your program while it is in storage and resume 
execution. 

If, for example, the error occurred because you had forgotten to 
initialize a register to contain a zero, you could use the DEBUG 
subcommand SET to place a zero in the register, and then resume 
execution with the GO subcommand. You can use the GO subcommand to 
specify the instruction address at which you want execution to begin: 

set gpr 11 0000 
go 200B0 

An alternate method of specifying a starting address at which execution 
is to resume is by using the SET subcommand to change the last word of 
the PSH: 

set psw 000200B0 
go 



( 
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If your program executes successfully, you can then make the 
necessary changes to your source file, recompile, and continue testing. 



Using DEBUG Subcommands to Monitor Program 
Execution 

The preceding examples did not represent a wide range of the 
possibilities for DEBUG subcommands. Nor do they represent the only way 
to approach program debugging. Some additional DEBUG subcommands are 
illustrated below. For complete details in using these subcommands, 
refer to the VM/370 CMS Command and Macro Reference. 

When you prepare to debug a program with known problems, or when you 
are beginning to debug a program for the first time, you might want to 
stop program execution at various instructions and examine the 
registers, constants, buffers, and so on. To temporarily stop program 
execution, use the BREAK subcommand to set breakpoints. You should set 
breakpoints after you load the program into storage, but before you 
begin executing it. You can set up to 16 breakpoints at one time. For 
each breakpoint, you assign a value (id) , and an instruction address: 

load myprog 

debug 

break 20BC0 

break 1 20C10 

break 2 20D00 

Then, you can return to CMS and begin execution: 

return 
start 

When the first breakpoint in this example is encountered, you receive 
the messages: 

DEBUG ENTERED. 
BREAKPOINT AT 20BC0 

Then, in the debug environment, use the subcommands GPR, CSW, CAW, PSW, 
and X to display registers, control words, or storage locations. 

You can resume program execution with the GO subcommand: 

go 

If, at any time, you decide that you do not want to finish executing 
your program, but want to return to the CMS environment immediately, you 
must use the HX subcommand: 

hx 

There are three subcommands you can use to exit from the debug 
environment: 

1. RETURN, to return to the CMS environment when DEBUG is entered with 
the DEBUG command 

2. GO, to resume program execution when it has been interrupted by a 
breakpoint 

3. HX, to halt program execution entirely and return to the CMS 
environment 
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If you try to leave the debag environment with the wrong subcommand you 
receive the message: 

INCORRECT DEBUG EXIT 

and you have to enter the proper subcommand. 



USING SYMBOLS WITH DEBUG 

To simplify the process of debugging in the CMS debug environment, you 
can use the ORIGIN and DEFINE subcommands. The ORIGIN command allows 
you to set an instruction location to serve as the base for all the 
addresses you specify. For example, if you specify: 

origin 20000 

then, to refer to your virtual storage location 201BC, you only need to 
enter: 

X Ibc 

By setting the DEBUG origin at your program's base address, you can 
refer to locations in your program by the virtual storage numbers in the 
listing, rather than having to compute the actual virtual storage 
address each time. The current DEBUG origin stays in effect until you 
set it to a different value or until you reload CMS (with the IPL 
command) . 

You can use the DEFINE subcommand to assign symbolic names to storage 
locations so that you can reference those locations by symbol, rather 
than by storage address. For example, suppose that during a DEBUG 
session you will repeatedly be examining three particular storage 
locations labeled in your program NAME 1, NAME2, and NAMES. They are at 
locations 20EF0, 20EFA, and 20F0a. Enter: 

load nameprog 

debug 

origin 20000 

define namel EFO 10 

define name2 EFA 10 

define name3 FOa 10 

break 1 a04 

return 

start 

When the specified breakpoint is encountered, you can examine these 
storage areas by entering: 

X namel 
X name2 
X names 

You can also refer to these symbols by name when you use the STORE 
subcommand: 

store name2 c4c5cSc5c1e4e5d6c9d9 

The names you specify do not have to be the same as the labels in the 
program; you can define any name up to eight characters. 

Figure 17 summarizes the DEBUG subcommands. 



21U IBM VM/S70 CMS User's Guide 



( 



) 



SubcoBBand Foraat 



Function 



BReak id /syBbol\ 



f syBbol^ 
( hexlocj 



CAW 



CSW 



r T 

DEFine syBbol hexloc |bytecount| 

I a I 

L J 



r r n n 

DUbp IsyaboH |syBbol2| [ident] | 

Ihexlod |hexloc2| j 

I I * I I 

L t 32 J J 



r T 

GO I symbol I 

I hexlocj 



GPR regl [reg2] 



HX 



r T 

ORigin | symbol! 
I hexloc I 
I I 



PSW 



RETurn 



SET ( CAH hexinf o 

CSW hexinf o [ hexinf o] 

PSW hexinf o [ hexinf o] 

GPR reg hexinf o [ hexinf o] 



STore {symbol} hexinf o [ hexinf o] 
{hexloc} 



r T 

X I symbol | n I 
I length I 

L J 



hexloc 



r T 

I n I 

I a I 

L J 



Stops program execution at the 
specified breakpoint. 



Displays the contents of the 
channel address word. 



Displays the contents of the 
channel status word. 



Assigns a symbolic name to the 
virtual storage address. 



Dumps the contents of specified 
virtual storage locations to the 
virtual spooled printer. 



Returns control to your program 
and starts execution at the 
specified location - 



Displays the contents of the 
specified general registers. 



Halts execution and returns to 
the CMS command environment. 



Specifies the base address to be 
added to locations specified in 
other DEBUG subcommands. 



Displays the contents of the old 
program status word. 



Exits from debug environment to 
the CHS command environment. 



Changes the contents of specified 
control words or registers. 



Stores up to 12 bytes of informa- 
tion starting at the specified 
virtual storage location. 



Examines virtual storage 
locations. 



Figure 17. Summary of DEBUG Subcommands 
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What To Do When Your Program Loops 

If, when your program is executing, it seems to be in a loop, you should 

first verify that it is looping, and then interrupt its execution and ( 

either (1) halt it entirely and return to the GHS environment or (2) 

resume its execution at an address outside of the loop. 

The first indication of a program loop may be either what seems to be 
an unreasonably long processing time, or, if you have a blip character 
defined, an inordinately large number of blips. 

You can verify a loop by checking the PSW frequently- If the last 
word repeatedly contains the same address, it is a fairly good 
indication that your program is in a loop. You can check the PSW by 
using the Attention key to enter the CP environment. You are notified 
by the message: 

CP 

that your virtual machine is in the CP environment. You can then use 
the CP command DISPLAY to examine the PSW: 

cp display psw 

and then enter the command BEGIN to resume program execution: 

cp begin 

If you are checking for a loop, you might enter both commands on the 
same line using the logical line end: 

cp d p#b 

When you have determined that your program is m a loop, you can halt l 
execution using the CMS Immediate command HX. To enter this command, ^ 
you must press the Attention key once to interrupt program execution, 
then enter: 

hx 

If you want your program to continue executing at an address past the 
loop, you can use the CP command BEGIN to specify the address at which 
you want to continue execution: 

cp begin 20cd0 

Or, you could use the CP command STORE to change the instruction address 
in the PSW before entering the BEGIN command: 

cp store psw 20cd0#begin 



Tracing Program Activity 

When your program is in a loop, or when you have a program that takes an 
unexpected branch, you might need to trace the execution closely to 
determine at what instruction the program goes astray. There are two 
commands you can use to do this. The SVCTRACE command is a CHS command 
which traces all SVCs (supervisor calls) in your program. The TRACE 
command is a CP command which allows you to trace different kinds of 
information, including supervisor call instructions. 



( 
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USING THE CP TRACE COMMAND 

You can trace the following kinds of activity in a program using the CP 
TRACE command: 

• Instructions 

• Branches 

• Interrupts (including program, external, I/O and SVC interrupts) 

• I/O and channel activity 

When the TRACE command executes, it traces all your virtual machine's 
activity; when your program issues a supervisor call, or calls any CMS 
routine, the TRACE continues. 

You can make most efficient use of the TRACE command by starting the 
trace at a specific instruction location. You should set an address 
stop for the location. For example, if you are going to execute a 
program and you want to trace all of the branches made, you would enter 
the following sequence of commands to begin executing the program and 
start the trace: 

load progress 

cp adstop 20004 

start 

ADSTOP AT 2000U 

cp trace branch 

cp begin 

Now, whenever your program executes a branch instruction, you receive 
information at the terminal that might look like this: 

02001E BALR 05E6 ==> 020092 

This line indicates that the instruction at address 2001E resulted in a 
branch to the address 020092. When this information is displayed, your 
virtual machine is placed in the CP environment, and you must use the 
BEGIN command to continue execution: 

cp begin 

When you locate the branch that caused the problem in your program, you 
should terminate tracing activity by entering: 

cp trace end 

and then you can use CP commands to continue debugging or you can use 
the EXTERNAL command to cause an external interruption that places your 
virtual machine in the debug environment: 

cp external 

You receive the message: 

DEBUG ENTERED. 
EXTERNAL INTERRUPT 

And you can use the DEBUG subcommands to investigate the status of your 
program. 
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Controlling a CP Trace 

There are several things you can do to control the amount of information i 
you receive when you are using the TRACE command, and how it is ^ 
received. For example, if you do not want program execution to halt 
every time a trace output message is issued, you can use the RUN option: 

cp trace svc run 

Then, you can halt execution by pressing the Attention key when the 
interruption you are waiting for occurs. You should use this option if 
you do not want to halt execution at all, but merely want to watch what 
is happening in your program. 

Similarly, if you do not require your trace output immediately, you 
can specify that it be directed to the printer, so that your terminal 
does not receive any information at all: 

cp trace inst printer 

When you direct trace output to a printer, the trace output is mixed in 
with any printed program output. If you want trace output separated 
from other printed output, use the CP DEFINE command to define a second 
printer at a virtual address lower than that of your printer at OOE. For 
example: 

cp define printer 006 

Then, trace output will be in a separate spool file. CBS printed output 
always goes to the printer at address OOE. 

When you finish tracing, use the CP CLOSE command to close the 
virtual printer file: / 



cp close e 

— or — 

cp close 006 

If you want trace output at the printer and at the terminal, you can use 
the BOTH option: 

cp trace all both 



Susgendinj Tracins 

If you are debugging a program that does a lot of I/O, or that issues 
many SVCs, and you are tracing instructions or branches, you might not 
wish to have tracing in effect when the supervisor or I/O routine has 
control, when you notice that addresses being traced are not in your 
program, you can enter: 

cp trace end 

and then set an address stop at the location in your program that 
receives control when the supervisor or I/O routine has completed: 

cp adstop 20688 
begin 
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Then, when this address is encountered, you can re-enter the CP THACE 
conmand. 



USING THE SVCTRACE COMMAND 

If your program issues nany SVCs, you may not get all of the information 
you need using the CP TRACE command. The SVCTBACE command is a CHS 
command, which provides more detailed information about all SVCs in your 
program, including register contents before and after the SVC, the name 
of the called routine, and the location from which it was called, and 
the contents of the parameter list passed to the SVC. 

The SVCTRACE command has only two operands, ON and OFF, to begin and 
end tracing. SVCTRACE information can be directed only to the printer, 
so you do not receive trace information at the terminal. 

Since the SVCTRACE command can only be entered from the CHS 
environment, you must use the Immediate commands SO (suspend tracing) or 
HO (halt tracing) if you want tracing to stop while a program is 
executing. Use the Immediate command RO to resume tracing. 

Since the CMS system is "SVC-driven", this debugging technigue can be 
useful, especially, when you are debugging CMS programs. For more 
information on writing programs to execute in CMS, see "Section 13. 
Programming for the CMS Environment." 



Using CP Debugging Commands 

In addition to the CMS debugging facilities, there are CP commands that 
you can use to debug your programs. These commands are: 

• DISPLAY, which you can use to examine virtual storage, registers, or 
control words, like the PSW 

• ADSTOP, which you can use to set an instruction address stop in your 
program 

• STORE, which you can use to change the contents of a storage 
location, register, or control word 

When you use the display command, you can request an EECDIC translation 
of the display by prefacing the location you want displayed with a "T": 

cp display t20000.10 

This command requests a display of XMO' (16) bytes beginning at 
location X» 20000*. The display is formatted four words to a line, with 
EBCDIC translation at the left, much as you would see it in a dump. 

Tou can also use the DISPLAY command to examine the general 
registers. For example, the commands: 

cp display g 
cp display g1 
cp display g2-5 

result in displays of all the general registers, of general register 1, 
and of a range of registers 2 through 5. 
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The DISPLAY command also displays the PSW, CAH^ and CSH: 

cp display psw 
cp display caw 
cp display csw 

With the STORE command, you can change the contents of registers, 
storage areas, or the PSW. 

As you can see, the CMS DEBUG subcommands and the CP commands ADSTOP, 
DISPLAY, and STORE, have many duplicate functions. The environment you 
choose to work in, CP or debug, is a matter of personal preference. The 
differences are summarized in Figure 18. What you should be aware of, 
however, is that you should never attempt to use a combination of CP 
commands and DEBUG subcommands when you are debugging a program. Since 
DEBUG itself is a program, when it is running (that is, when you are in 
the debug environment) , the registers that CP recognizes as your virtual 
machine's registers are actually the registers being used by DEBUG. 
DEBUG saves your program's registers and PSW and keeps them in a special 
save area. Therefore, if you enter the DEBUG and CP commands to display 
registers, you will see that the register contents are different: 

gpr 15 
#cp d g 



DEBUGGING WITH CP AFTER A PROGRAM CHECK 

When a program that is executing under CMS abends because of a program 
check, the DEBUG routine is in control and saves your program's 
registers, so that if you want to begin debugging, you must use the 
DEBUG command to enter the debug environment. 

You can prevent DEBUG from gaining control when a program 
interruption occurs by turning on the wait bit in the program new PSW 
(location X'68' in low storage) : 

cp store 68 00020000 

You should do this before you begin executing your program. Then, if a 
program check occurs during execution, when CP tries to load the program 
new PSW, the wait bit forces CP into a disabled wait state and you 
receive the message: 

DMKDSP450W CP ENTERED; DISABLED WAIT PSW 

All of your program's registers and storage areas remain exactly as they 
were when program interruption occurred. The PSW that was in effect 
when your program was interrupted is in the program old PSW, at location 
X'28'. Use the DISPLAY command to examine its contents: 

cp display 28.8 

The program new PSW, or the PSW you see if you enter the command DISPLAY 
PSW, contains the address of the DEBUG routine. 

If, after using CP to examine your registers and storage areas, you 
can recover from the problem, you must use the STORE command to restore 
the PSW, specifying the address of the instruction just before the one 
indicated at location X'28'.- For example, if the instruction address in 
your program is X'566' enter: 
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cp store psw 20566 
cp begin 

In this example, setting the first word of the PSW to turns the wait 
bit off, so that execution can resume. 

Program Dumps 

When a program you execute under CMS abnormally terminates, you do not 
automatically receive a program dump. If, after attempting to use CMS 
and CP to debug interactively, you still have not discovered the 
problem, you may want to obtain a dump. You might also want to obtain a 
dump if you find that you are displaying large amounts of information, 
which is not practical on a terminal. 

Depending on whether you are using CMS DEBUG or CP to do your 
debugging, you can use the DUMP command to specify storage locations you 
want printed. The formats of the DUMP command (CP) and the DUMP 
subcommand (DEBUG) are a little different. See yM/370 CMS Command and 
Macro Reference for a discussion of the DEBUG subcommand, DUMP; see 
YM/370 CP Command Reference for General Users for a discussion of the CP 
DUMP command. 

In either event, you can selectively dump portions of your virtual 
storage, your entire virtual storage area, or portions of real storage. 
For example, in the debug environment, to dump the virtual storage space 
that contains your program, you would enter: 

dump 20000 20810 

The second value depends upon the size of your program. 

From the CP environment, enter: 

cp dump t20000-20810 

The CP DUMP command allows you to reguest EBCDIC translation with the 
hexadecimal dump. The dump produced by the DEBUG subcommand does not 
provide EBCDIC translation. 

Debugging Modules 

YOU can debug nonrelocatable MODULE files (created with the GENMOD 
command) in the same way you can debug object modules (TEXT files). 

To load the MODULE into storage, use the LOADMOD command: 

loadmod mymod 
cp adstop 201C0 
start 

If you make any changes to the module while it is in your virtual 
storage area and then issue the GENMOD command, the changes are a 
permanent part of the executable module: 

loadmod mymod 

cp store 201C0 0002 

genmod mymod 

To debug MODULE files in this manner, you must have a listing of the 
program as it existed when the module was created. 
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Comparison of CP and CMS Facilities for Debugging 

If you are debugging problems while running CMS, you can choose the CP or CMS debugging 
tools- Rpfer to Figure 18 for a comparison of the CP and CMS debugging tools. 



r ■ "■■ - ' ■ 

1 Function I CP I CMS 


1 Setting | Can set only one address stop at a time. | Can set up to 16 address stops 
1 address | I at a time. 
1 stops. 1 i 


1 lumping I The dump is printed in hexadecimal format | The dump is printed in hexa- 
1 contents | with EBCDIC translation. The storage ad- | decimal format. The storage 
jof storage! dress of the first byte of each line is | address of the first byte of 
jto the 1 identified at the left. j each line is identified at the 
1 printer. | | left. The contents of general 
1 1 1 and floating-pcjtDt registers 

I 1 1 are printed at the beginning 

II 1 of the dump. 


1 Displaying! The display is typed in hexadecimal format | The display is typed in hexa— 
jthe con- j with EBCDIC translation. The CP command | decimal format. Tie CMS ccm- 
1 tents of I displays storage keys, floating-point regi-j mands do not display storage 
(storage j sters and control registers. I keys, floating— point registers 
land 1 1 or control registers as the CP 
(control 1 1 command does, 
(registers j I 
(at the ( 1 
(terminal. | j 


1 Storing | The amount of information stored by the CP | The CMS command stores up to 

(infcrma- ( command is limited only by the length of ( 12 bytes of information. CMS 

(tion- j the input line. The information can be j stores data in the general 

( ( full word aligned when stored. CP stores | registers but net in the 

1 1 data in floating— point and control regis— | floating-point or control reg- 

1 j ters, as well as in general registers. CP j isters. CMS stores data in the 

1 1 stores data in the PSW, but not in the CAW ( PSH, CAW, and CSW. 

j ( or CSW. However, data can be stored in the ( 

1 1 CSW or CAW by specifying the hardware ad— | 

1 { dress in the STORE command. | 


1 Tracing | CP traces: I CMS traces all SVC interrup— 

jinforma- ( • All interruptions, instructions, and | tions. CMS displays the 

(tion. ( branches j contents of general and 

( ( • SVC interruptions ( floating-point registers 

( ( • I/O interruptions ( before and after a routine is 

( 1 • Program interruptions j called. The parameter list is 

j 1 • External interruptions I recorded before a 

( 1 • Privileged instructions I routine is called. 

1 1 • All user I/O operations I 

I ( • Virtual and real CCW*s j 

i j • All instructions I 

1 1 The CP trace is interactive. You can stop | 
I 1 it and display other fields. I 



Figure 18. Comparison of CP and CMS Facilities for Debugging 
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What Your Virtual Machine Storage Looks Like 

Figure 19 illustrates a simplified CMS storage map. The portion of 
storage that is of most concern to you is the user program area, since 
that is where your programs are loaded and executed. The user program 
area and some of the other areas of storage shown in the figure are 
discussed below in general terms. 

When you issue a LOAD command (for OS or CMS programs) or a FETCH 
command (for DOS programs), and you do not specify the OBIGIN option, 
the first, or only, program you load is loaded at location X«20000«, the 
beginning of the user program area. 

The upper limit, or maximum size, of the user program area is 
determined by the storage size of your virtual machine. You can find 
out how large your virtual machine is by using the CP QUERY command: 

cp guery virtual storage 

If you need to increase the size of your virtual machine, then you 
must use the CP command DEFINE. For example: 

cp define storage 102Uk 

increases the size of your virtual machine to 102UK bytes. If you are 
in the CMS environment when you enter this command, you receive a 
message like: 

STORAGE = 01024K 

DMKDSP450H CP ENTERED; DISABLED WAIT PSW VCC020000 OOOOGOOO* 

and you must reload CHS with the IPL command before you can continue. 

You might need to redefine your virtual machine to a larger size if 
you execute a program that issues many requests for free storage, with 
the OS GETMAIN or DOS/VS GETVIS macros. CMS allocates this storage from 
the user program area. 

At the top of the user program area are the loader tables, that are 
used by the CMS loader to point to programs that have have been loaded. 
You can increase the size of this area with the CMS SET LDRTBLS command. 
If you use the SET LDRTBLS command, you should issue it immediately 
after you IPL CMS. 

The transient program area is used for loading and executing 
disk-resident CMS MODULE files that have been created using the ORIGIN 
TRANS option of the LOAD command, followed by the GENMOD command. For 
more information on CMS MODULE files and the transient area, see 
"Executing Program Modules" in "Section 13. Programming for the CMS 
Environment." 



SHARED AND NONSHARED SYSTEMS 

The areas in storage labeled in Figure 19 as the CMS nucleus and the 
DCSS are system programs that are loaded by various types of requests. 
When you enter the command: 

cp ipl cms 
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Figure 19, Simplified CMS Storage Map 

the area shown as the CMS nucleus is loaded with the CMS system, which 
is known to CP by its saved name, CMS. This saved system is a copy of 
the CMS system that is available for many users to share. When you are 
using CMS, you share it with other users who have also issued the IPL 
command to load the saved CMS system. By having many users share the 
same system, CP can manage system resources more efficiently. 

Under some circumstances, you may need to load the CMS system into 
your virtual machine by entering the IPL command as follows: 

cp ipl 190 

This IPL command loads the CMS system by referring to its virtual 
address, which in most installations is 190. The copy of CMS you load 
this way is nonshared; it is your own copy, but it is the same system, 
functionally, as the saved system CMS. 

Some of the CP and CMS debugging commands do not allow you to trace 
or store information that is contained in shared areas of your virtual 
machine. For example, if you have entered the command: 

cp trace inst 
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to trace instructions in your virtual machine, some of the instructions 
may be located in the CMS nucleus. If you have a shared copy of CMS, you 
receive a message like: 



DMKATS181E SHARED SYSTEM CMS 



REPLACED WIIB NOKSHARED COPY 



and CP loads a copy of CMS for you that you do not share with other 
users. 



I Discontiguous Saved Segments (DCSS) 

Some CMS routines and programs are stored on disks and loaded into 
storage as needed. These segments include the CMS editor, EXEC 
processor, and OS simulation routines; CMS/EOS; VSAM; and access method 
services- Beyond the end of your virtual machine address space is an 
area of storage into which these segments are loaded when you need them. 
Since this area is not contiguous with your virtual storage, the 
I segments that are loaded in this area are called discontiguous saved 
segments. 

These segments are loaded only when you need them, and are released 
from the end of your virtual machine when you are through using them. 
Like the CHS system, they are saved systems and can be shared by many 
users. For example, whenever you issue the EDIT command the segment 
named CMSSEG is loaded; when you enter the EEIT subcommands FILE or 
QUIT, the saved system CMSSEG is released. The other segments are named 
CMSDOS (for CMS/DOS) , CMSVSAM (for VSAM interfaces) , and CMSAMS (for 
access method services interfaces) . These names are the defaults; they 
can be changed by the installation. 

You can specifically reguest a nonshared copy of a segment by loading 
the named system by volume rather than by name. If you do not do this 
before altering a shared segment (unless with the AESTOP, TRACE, or 
STORE CP commands), CP issues the message DMKVMSU56W and places you in 
console function mode. 



In addition, for the CMSSEG segment only, you can indicate an 
alternate segment to be loaded on the IPL command. The format of the 
IPL command to support this is: 



IPL 



cuu 
systemname 



PARM SEG=segmentname 



where: 



SEG=segmentname 

indicates the name of the saved segment to be loaded whenever the 
CMS editor, EXEC processor, or OS simulation routines are needed. 
Eight characters jnust be entered for segmentname; either assign an 
eight-character segment name when you code the NAMESYS macro for 
your installation, or be sure that the operator enters trailing 
blanks if segmentname is less than eight characters long. 

The CMS batch facility loads whatever segment is specified on the 
first IPL command issued for the batch virtual machine. Thus, if the 
first IPL command for a CMS batch facility machine is: 

IPL CMS PARM SEG=CMSSEG02 



) 



all subseguent IPL commands issued by 
specify the same segment name (CMSSEG02) . 



the CMS batch facility will 



For additional information on saved systems, discontiguous saved 
segments, and CMS virtual storage, see the VM2^370 System Proqtammer *s 
Guide. 
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Section 12. Using the CMS Batch Facility 



The CMS batch facility provides a way of submitting jobs for batch 
processing in CMS. You can use the CMS batch facility when: 

• You have a job (like an assembly or execution) that takes a lot of 
time, and you want to be able to use your terminal for other work 
while the time-consuming job is being run. 

• You do not have access to a terminal. 

The CMS batch facility is really a virtual machine, generated and 

controlled by the system operator, who logs on VM/370 using the batch 
userid and invoking the CMSBATCH command. All jobs submitted for batch 

processing are spooled to the userid of this virtual machine, which 

executes the jobs sequentially. To use the CMS batch facility at your 

location, you must ask the system operator what the userid of the batch 
virtual machine is- 



Submitting Jobs to the CMS Batch Facility 

Under a real OS or DOS system, jobs submitted in batch mode are 
controlled by JCL specifications. Batch jobs submitted to the CMS batch 
facility are controlled by the control cards /JOB, /SET, and /*, and by 
CMS commands. 

Any application or development program written in a language 
supported by VM/370 may be executed on the batch facility virtual 
machine. However, there are restrictions on programs using certain CP 
and CMS commands, as described later in this section. 



INPUT TO THE BATCH MACHINE 

Input records must be in card-image format, and may be punched on real 
cards, placed in a CMS file with fixed-length, 80-character records, or 
punched to your virtual card punch. These jobs are sent to the batch 
virtual machine in one of two weiys: 

• By reading the real punched card input into the system card reader 

• By spooling your virtual card punch to the virtual reader of the 
batch virtual machine 

When you submit a real card deck to the batch machine, the first card 
in the deck must be a CP ID card. The ID card takes the form: 



I ID userid I 

I 1 

where ID must begin in card column one and be separated from userid (the 
batch facility virtual machine userid) by one or more blanks. 
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For example, if your installation's batch virtual machine has a 
userid of BATCHI, you punch the card: 

ID BATCH1 

and place it in front of your deck. 

When you are going to submit a job using your virtual card punchy you 
must first be sure that your punch is spooled to the virtual reader of 
the batch virtual machine: 

cp spool punch to batchi 



Submitting Virtual Card In£ut to the CMS Batch Facility; 

Virtual card input can be spooled to the batch machine in several ways. 
You may create a CMS file that contains the input control cards and use 
the CMS PUNCH command to punch the virtual cards: 

punch batch jcl (noheader 

When you punch a file this way, you must use the NOHEADER option of the 
PUNCH command, since the CMS batch facility cannot interpret the header 
card that is usually produced by the PUNCH command. As it does with 
cards in an invalid format, the batch virtual machine would flush the 
header card. 

You can use an EXEC procedure to submit input to the batch machine. 
From an EXEC, you can punch one line at a time into your virtual punch, 
using the SPUNCH and SBEGPUNCH EXEC control statements. When you do 
this, you must remember to use the CP CLOSE command to release the spool 
punch file when you are finished: 

CP CLOSE PUNCH 

If you are using the EXEC to punch individual lines and entire CMS files 
to be read by the batch virtual machine as one continuous job stream, 
you must remember to spool your punch accordingly: 

CP SPOOL PUNCH CONT 
SPUNCH /JOB BOSHELL 999888 
PUNCH BATCH JCL * (NOHEADER 
CP SPOOL PUNCH NOCONT 
CP CLOSE PUNCH 



The /JOB and /* Cards 

A /JOB card must precede each job to be executed under the batch 
facility. It identifies your userid to the batch virtual machine and 
provides accounting information for the system. It takes the form: 

I 1 

I /JOB userid accntnum [ jobname] [comments] I 

I 1 



( 
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where : 

userid is your user identification, or the userid under which you 
want the job submitted. This parameter controls: (1) The 
userid charged by the CP accounting routines for the system 
resources used during a job- (2) The name and distribution 
code that appear on any spooled printer or punch output. (3) 
The userid to whom status messages are sent while the batch 
machine is executing the job. 

Note that items 1 and 2 are correct only if the directory for 
the userid involved contains the accounting option. 

accntnum is your account number. This account number appears in the 

accounting data generated at the end of your job. It 

overrides the account number in the CP directory entry for the 
userid specified for this job. 

jobname is an optional parameter that specifies the name of the job 
being run. If you specify a jobname, it appears as the CP 
spool file identification in the filetype field. The filename 
field always contains CMSBATCH. See "Batch Facility Output" 
below. 

comments may be any additional information you want to provide. 



The /* card indicates the end of a job 
takes the form: 



to the batch facility. It 



I /* 

I 



The batch facility treats all /* cards after the first as null cards. 
Therefore, if you want to ensure against the previous job not having a 
/* end— of— job indicator, you should precede your /JOB card with a /* 
card. 



The /* card is also treated as an end-of— file indicator when a file 
is being read from the input stream. This is a special technique used in 
submitting source or data files through the card reader and is discussed 
under "A Batch EXEC for Non-CMS Users." 



The /SET Card 



The /SET card sets limits on a system's time, printing, and punching 
resources during the execution of a job. It takes the form: 



I /SET [TIME seconds] [PRINT lines] [PUNCH cards] 
I 



where: 
seconds 

lines 



is a decimal value that specifies the maximum number of 
seconds of virtual CPU time a job can use. 

is a decimal value that specifies the maximum number of lines 
a job can print. 
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cards is a decimal number that specifies the maximum number of cards 
a job can punch. 

The default values for the batch facility are set at 32,767 seconds, 
printed lines, and punched cards per job. Any nev limits defined using 
the /SET card must be less than these maximum settings. The system 
resources can be set at lesser values than the default values by an 
installation's system programmer; be sure you know the maximum 
installation values for batch resource limits before you use the /SET 
card. 

A /SET card can appear anywhere in the job following the /JOB card. 
The new limits defined by the /SET card apply only to the part of the 
job that follows the /SET card. 

A job can contain up to three /SET cards (one for each operand) ; a 
/SET card cannot be entered more than once for the same operand. 

Only use /SET cards for the operands whose values you want to change 
from the default; the default values are reset between jobs. A /SET 
card for an operand overrides its default but does not reset the other 
operands. 



HOW THE BATCH FACILITY WORKS 



The CMS batch facility, once initialized, runs continuously. When it 
begins executing a job, it sends a message to the userid of the user 
submitting the job- If you are logged on when the batch machine begins 
executing a job that you sent it, you receive the message: 

BSG FROM BATCHID: JOB • your job • STARTED 

When the batch machine finishes processing a job, it sends the message: 

MSG FROM BATCHID: JOB 'your job* ENDED 

where yourjob is the jobname you specified on the /JOB card. Before it 
reads the next job from its card reader, the batch virtual machine: 

• Closes all spooling devices and releases spool files 

• Resets any spooling devices identified by the CP TAG command 

• Detaches any disk devices that were accessed 

• Punches accounting information to the system 

• Reloads CMS 

All of this "housekeeping" is done by the CMS batch facility so that 
each job that is executed is unaffected by any previous jobs. 

If a job that you sent to the batch virtual machine terminates 
abnormally (abends) , the batch machine sends you a message: 

MSG FROM BATCHID: JOB 'yourjob* ABEND 

and spools a CP storage dump of your virtual machine to the printer. 
The remainder of your job is flushed. 

Whenever the batch virtual machine has read and executed all of the 
jobs in its card reader, it waits for more input. 



( 
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Preparing Jobs for Batch Execution 

When you want to submit a job to the CMS batch facility for execution, 
you should provide the same CMS and CP commands you would use to prepare 
to execute the same job in your own virtual machine. 

You must provide the batch virtual machine with read access to any 
disk input files that are required for the job. You do this by supplying 
the LINK and ACCESS command lines necessary. The batch virtual machine 
has an A-disk (195) , so you can enter commands to access your disks as 
read-only extensions. For example, if you wanted the batch machine to 
execute a program module named LONDON on your 291 disk, your input file 
might contain the following: 



/JOB FISH 012345 

CP LINK BOSHELL 291 291 RR SECRET 

ACCESS 291 B/A 

LONDON 



Similarly, if you are using the batch virtual machine to execute a 
program using input and output files, you must supply the file 
definitions: 



CP LINK ARDEN 391 391 RR FOREST 

ACCESS 391 B/A 

FILEDEF INFILE DISK VITAL STAT B 

FILEDEF OUTFILE PONCH 

CP SPOOL PONCH TO BOSHELL 

LONDON 



If you expect printed or punched output from your job, you may need 
to include the spooling commands necessary to control the output. In 
the above example, the batch machine's punch is spooled to user id 
BOSHELL* s virtual reader. 

Any output printer files produced by your job are spooled by the 
batch virtual machine to the printer. These files are spooled under your 
userid and with the distribution code associated with your userid, 
provided the userid' s directory has the accounting option set. You can 
change the characteristics of these output files with the CP SPOOL 
command: 



CP SPOOL E CLASS T 



If you want output to appear under a name other than your userid, use 
the FOR operand of the SPOOL command: 



CP SPOOL E FOR JONSON 



) 



Output punch files are spooled, by default, to the real system card 
punch (under your userid) , unless you issue a SPOOL command in the batch 
job to control the virtual card punch of the batch virtual machine. 
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RESTRICTIONS ON CP AND CMS COMMANDS IN BATCH JOBS 

The batch facility permits the use of many CP and most CMS commands. 
The following CP commands can be used to control the batch virtual 
machine: 



CHANGE! 


MSG 


CLOSEi 


QUERY 


DETACH2 


REWIND 


DUMP 


SMSG 


DISPLAY 


SPOOL* 


LINK3 


STORE 




TAG 



Notes; 

1. These commands may not be used to affect the virtual card reader. 

2. You can not use this command to detach any spooling devices or the 
system or IPL disks. 

3. The LINK command must be entered on one line in the format: 

CP LINK userid vaddr vaddr mode password 

None of the LINK command keywords (AS, PASS, TO) are accepted. If 

the disk has no password associated with it, you must enter the 

password as ALL. A maximum of ten links may be in effect at any 
one time. 

All CP commands in a batch job must be prefaced with the "CP" 
command. 

Since the batch virtual machine reads input from its card reader, you ,, 
cannot use the following commands or operands that affect the card (| 
reader: 

ASSGN SYSxxx READER (CMS/DOS only) 
DISK LOAD 
FILEDEF READER 
READCARD 

I The RDCARD macro cannot be used by jobs that run under the CMS batch 
I machine. 

Invalid SET command operands are: 



BLIP 


OUTPUT 


EMSG 


REDTYPE 


IMPCP 


RELPAGE 


INPUT 


PROTECT 



All the other operands of the SET command can be used in a job executing 
in the batch virtual machine. 



BATCH FACILITY OUTPUT 

Any files that you request to have printed during your job*s execution 
are spooled to the real system printer under your userid, unless you 
have spooled it otherwise. Once released for processing, these output 
files are under the control of the CP spooling facilities; if you are 
logged on, you can control the disposition of these files before they 
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I are printed with the CLOSE, PURGE, ORDER, and CHANGE commands. See the 
I following section "Purging, Reordering, and Restarting Batch Jobs." 

Output files produced by the batch virtual machine are identifiable 
by the filename CMSBATCH in the CP spool file name field. The spool file 
type field contains the filetype JOB, unless you specified a jobname on 
the /JOB card. This applies to both printer and punch output files. 

In addition to your regular printed output, the CMS batch facility 
spools a console sheet that contains a record of all the lines read in, 
and the responses, error messages, and return codes that resulted from 
command or program execution- This file is identified by a spool file 
name of BATCH and a spool file type of CONSOLE. 



I PURGING, REORDERING, AND RESTARTING BATCH JOBS 



) 



When required, you can control the execution of batch virtual machine 
jobs by purging, reordering, and restarting them; by the same token, 
because all the closed printer files are queued for system output under 
the submitting userid, you can change, purge, or reorder these files 
prior to processing on the system printer. 

To purge a job executing under the batch monitor, follow the 
procedure below: 

1. Signal attention and enter the virtual machine environment. 

2. Enter the HX (halt execution) Immediate command. 

3. Disconnect the virtual machine using the CP DISCONN command- 

The HX command causes the batch facility to abnormally terminate. 
This provides the user with an error message and a CP dump of the batch 
facility virtual machine. The batch monitor then loads itself again and 
starts the next job (if any) . 

To purge an individual input spool file that is not yet executing, 
issue the CP PURGE command: 

PURGE READER spoolid 

In the format above, spoolid is the spool file number of the job to 
be purged from the batch virtual machine's job queue. For example, the 
statement: 

PURGE READER 123 

would purge 123 from the batch virtual machine's job queue. 

To reorder individual spool files in the batch facility's job queue, 
use the CP ORDER command: 

ORDER READER spoolidi spoolid2. .. 

In this format, spoolidi and spoolid2 are the assigned spool file 
identifications of the jobs to be reordered. 

You can determine which jobs are in the queue by using the CP QUERY 
command: 

QUERY READER ALL 
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This QUERY command lists the filenames and filetypes of all the jobs 
in the batch virtual machine's job queue. You can then reorder them, 
using the ORDER command. 



Using EXEC Files for Input to the Batch Facility 

There are a variety of ways that EXEC procedures can help facilitate the 
submission of jobs to the CMS batch facility. You can prepare an EXEC 
file that contains all of the CMS commands you want to execute^ and then 
pass the name of the EXEC to the batch virtual machine. For example, 
consider the files COPY JCL and COPYF EXEC: 

COPY JCL: /JOB CARBON 999999 
EXEC COPYF 
/* 

COPYF EXEC: COPYFILE FIRST FILE A SECOND = = 
COPYFILE THIRD FILE A FOURTH = = 

Then, if you enter the commands: 

cp spool punch to cmsbatch 
punch copy jcl * (noheader 

the commands in the EXEC file are executed by the batch virtual machine. 

You could also use an EXEC to punch input to the batch virtual 
machine. Using the same commands as in the example above, you might 
have an EXEC named BATCOPY: 

CP SPOOL PUNCH TO BATCH3 

SPUNCH /JOB CARBON 999999 

SPUNCH COPYFILE FIRST FILE A SECOND = = 

SPUNCH COPYFILE THIRD FILE A FOURTH = = 

SPUNCH /* 

CP CLOSE PUNCH 

Then, when you enter the EXEC name: 

batcopy 

the input lines are punched to the batch virtual machine. 

The examples above are very simple; you probably would not go to the 
trouble of sending such a job to the batch virtual machine for 
processing. The examples do, however, illustrate the two basic ways 
that you can use EXEC procedures with the batch facility: 

1. Invoking an EXEC procedure from a batch virtual machine 

2. Using an EXEC procedure to create a job stream for the batch 
virtual machine 

In either case, the EXECs that you use may be very simple or very 
complicated. In the first instance, an EXEC might contain many steps, 
with control statements to conditionally control execution, error 
routines, and so on. 

In the second instance, you might have an EXEC that is versatile so 
that it can be invoked with different arguments so as to satisfy more 
than one situation. For example, if you want to create a simple EXEC to 
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send jobs to the batch virtual machine to be assembled, it might 
contain: 



CP SPOOL PUNCH TO BATCH3 CONT 

8P0NCH /JOB ARIEL 888888 

SPUNCH CP LINK ARIEL 191 391 RR LINKPASS 

&PDNCH ACCESS 391 B/A 

6PUNCH ASSEMBLE Si (PRINT 

&PDNCH CP SPOOL PUNCH TO ARIEL 

SPUNCH PUNCH &1 TEXT A (NOHEADER 

&PUNCH /* 

CP SPOOL PUNCH NOCONT CLOSE 



If this file were named BATCHASM EXEC, then whenever you wanted the CKS 
batch facility to assemble a source file for you, you would enter: 



batchasm filename 



and the batch virtual machine would assemble the source file, print the 
listing, and send you a copy of the resulting TEXT file. 



SAMPLE SYSTEM PROCEDURES FOR BATCH EXECUTION 



) 



To extend the above example a little further, suppose you wanted to 
process source files in languages other than the assembler language. Ycu 
want, also, for any user to be able to use this EXEC. You might have a 
separate EXEC file for each language, and an EXEC to control the 
submission of the job. This example shows the controlling EXEC file 
BATCH and the ASSEMBLE EXEC. 



BATCH EXEC: 

THIS EXEC SUBMITS ASSEMBLIES/COMPILATIONS TO CMS BATCH 



1 



- PUNCH BATCH JOB CARD; 

- CALL APPROPRIATE LANGUAGE EXEC (S3) TO PUNCH EXECUTABLE COMMANDS 

SCONTROL ERROR 

SIF SINDEX GT 2 SSKIP 2 

STYPE CORRECT FORM IS: BATCH USERID FNAME IIYPE (LANGUAGE) 

8EXIT 100 

SERROR SGOTO -ERRi 

CP SPOOL D CONT TO BATCHCMS 

SPUNCH /JOB 61 1111 82 

SPUNCH CP LINK Si 191 291 RR SECRET 

SPUNCH ACCESS 291 B/A 

EXEC 83 82 81 

SPUNCH /* 

CP SPOOL D NOCONT 

CP CLOSE D 

CP SPOOL D OFF 

SEXIT 

-ERRI SEXIT 100 
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ASSEMBLE EXJC: 

* CORRECT PORM IS: ASSEMBLE FNAME OSERID 
* 

* PUNCH COMMANDS TO: 

* - INVOKE CMS ASSEMBLER 

* - RETURN TEXT DECK TO CALLER 
* 

SCONTROL ERROR 

SERROR SGOTO -ERR2 

SPUNCH GLOBAL MACLIB UPLIB CMSLIB OSMACRO 

5PUNCH CP MSG 82 ASMBLING • S1 • 

&PUNCH ASSEMBLE &1 (PRINT NOTERM) 

SPUNCH CP MSG 62 ASSEMBLY DONE 

&PUNCH CP SPOOL D TO 82 NOCONT 

8PUNCH PUNCH 81 TEXT Al (NOHEADER) 

8BEGPUNCH 

CP CLOSE D 

CP SPOOL D OFF 

RELEASE 291 

CP DETACH 291 

8END 

6EXIT 

-ERR2 8EXIT 102 



Executing the Samjgle EXEC Procedure 

If the above EXEC procedure is invoked with the line: 

batch fay payroll assemble 

the BATCHCMS virtual machine's card reader should contain the following 
statements (in the same general form as a FIFO console stack) : 

/JOB FAY 1111 PAYROLL 

CP LINK FAY 191 291 RR SECRET 

ACCESS 291 B/B 

GLOBAL MACLIB UPLIB CMSLIB OSMACRO 

CP MSG FAY ASMBLING • PAYROLL • 

ASSEMBLE PAYROLL (PRINT NOTERM) 

CP MSG FAY ASSEMBLY DONE 

CP SPOOL D TO FAY NOCONT 

PUNCH PAYROLL TEXT Al (NOHEADER) 

CP CLOSE D 

CP SPOOL D OFF 

RELEASE 291 

CP DETACH 291 

/* 

When the batch facility executes this job, the commands are executed as 
you see them: if you are logged on, you receive, in addition to the 
normal messages that the batch facility issues, those messages that are 
included in the EXEC. 



A BATCH EXEC FOR A NON-CMS USER 

Many installations run the CMS batch facility for non-CMS users to 

submit particular types of jobs. Usually, a series of EXEC files are £" 

stored on the system disk so that each user only needs include a card to ^ 
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invoke the EXEC, which executes the correct CMS commands to process data 
included with the job stream. 

For example, if a non-CMS user wanted to compile FORTRAN source 
files, the following BATFORT EXEC file could be stored on the system 
disk: 

&CONTROL OFF 

FILEDEF INHOVE TERM (RECFM F BLOCK 80 LRECL 80 

FILEDEF OOTMOVE DISK SI FORTRAN A1 (RECFM F LRECL 80 BLOCK 80 

MOVEFILE IN OUT 

GLOBAL TXTLIB FORTRAN 

FORTGI &1 (PRINT) 

&FORTRET = SRETCODE 

&IF &RETCODE NE 8G0T0 -EXIT 

PDNCH S1 TEXT A1 (NOHEADER) 

-EXIT SEXIT 8F0RTRET 

To use this EXEC, a non-CMS user might place the following real card 
deck in the system card reader: 

ID CMSBATCH 

/JOB JOEDSER 123U JOBIO 

BATFORT JOEFORT 

source file 

/* (end-of-file indicator) 
/* (end-of-job indicator) 

When the batch virtual machine executes this job, it begins reading 
the EXEC procedure from disk, and executes one line at a time. When it 
encounters the MOVEFILE command, it begins reading the source file from 
its card reader (the batch facility interprets a terminal read as a 
reguest to read from the card reader) . it continues reading until it 
reaches the end-of-file indicator (the /* card) , and then resumes 
processing the EXEC on the next line following the MOVEFILE command 
line. 

Additional functions may be added to this EXIC procedure, or others 
may be written and stored on the system disk to provide, for example, a 
compile, load, and execute facility. These EXEC procedures would allow 
an installation to accommodate the non-CMS users and maintain common 
user procedures. 
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Section 13. Programming for the CMS 
Environment 



This section contains information for assembler language programmers who 
may occasionally need to write programs to be used in the CMS 
environment. The conventions described here apply only to CMS virtual 
machines; you can not execute these programs under any other operating 
systems. 



Program Linkage 

Program linkages, in CMS, are generally made by means of a supervisor 
call instruction, SVC 202. The SVC handling routine takes care of 
program linkage for you- The registers used and their contents are 
discussed in the following paragraphs. 

Reg i ster V: Points to a parameter list of successive doublewords. The 
first entry in the list is the name of the called routine or program, 
and any successive doublewords may contain arguments passed to the 
program. Parameter lists are discussed under "Parameter Lists." 

l^jgister _13: Contains the address of a 2U-fullword save area, which you 
can use to save your caller's registers. This save area is provided to 
satisfy standard OS and DOS linkage conventions; you do not need to use 
it in CMS, since the SVC routines save the registers. 

Register 14: Contains the return address of the SVC handling routines. 
You must return control to this address when you exit from your program. 

The CMS routines that get control by way of register 14 close files, 
update your disk file directory, and calculate and type the time used in 
program execution. These values appear in the CMS ready message, which 
is displayed at your terminal when your program finishes execution: 

R;T=n.nn/x.xx hh:mm:ss 

where n.nn is the CMS CPU time (in seconds) and x.xx is the combined CP 
and CMS CPU time. hh:mm:ss is the time of day in hours, minutes, and 
seconds. 

Register 15: Contains your program's entry point address. You can use 
this address to establish immediate addressability in your program. You 
should not use it as a base address, however, since all CMS SVCs use it 
for communication with your programs. 

Figure 20 shows a sample CMS assembler language program entry and exit. 
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PROGRAM CSECT 

USING PROGRAM, 12 

LR 12,15 

ST 14,SA7RET 



ESTABLISH ADDRESSABILITY 
SAVE RETURN ADDRESS IN RlU 





L 


14, SAVRET 


LOAD RETURN ADDRESS 




LA 


15,0 


SET RETURN CODE IN R15 




BR 


14 


GO 


SAVRET 


DS 


F 


SAVE AREA 



Figure 20. Saiaple CMS Assembler Program Entry and Exit Linkage 



RETURN CODE HANDLING 



Register 15, in addition to its role in entry linkage, is also used in 
CMS as a return code register. All of the CMS internal routines pass a 
completion code by way of register 15, and the SVC routines that receive 
control when any program completes execution examine register 15. 



If register 15 contains a nonzero value, 
CMS ready message, following the "R": 

R (nnnnn) ;T=n.nn/x.xx hh:mm:ss 



this value is placed in the 



When you are executing programs in CMS, it is good practice, if your 
programs do not use register 15 as a return code register, to place a 
zero in it before transferring control back to CMS. Otherwise, the ready 
message may display meaningless data. 



PARAMETER LISTS 



When you execute a program from your terminal, a CMS scan routine sets 
up a parameter list based on your command input line. The parameter list 
is doubleword-aligned, with parameters occupying successive doublewords. 
The scan routine recognizes blanks and parentheses as argument 
delimiters; parentheses are placed, in the parameter list, in separate 
doublewords. 

For example, if you have a CMS MODULE file named TESTPROG, and you 
call it with the command line: 

testprog (f ile2) 

The scan routine sets up the parameter list: 

CMNDLIST DS CD 

DC CL8 'TESTPROG' 

DC CL8»(» 

DC CL8»FILE2' 

DC CL8») » 

DC 8X»FF« 

The last doubleword is made up of all Is, to act as a delimiter. 

If you enter any argument longer than eight characters, it is 
truncated and only the first eight characters appear in the list. 
However, no error condition results. 



( 
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5sisa Parameter Lists 

The scan routine that sets up this parameter list places the address of 
the list in register 1 and then calls the SVC handling routine. The SVC 
routine gives control to the program named in the first doubleword of 
the parameter list- 

Hhen your program receives control, it can examine the parameter list 
passed to it by way of register 1. 

YOU can use this technique, also, to call CMS commands from your 
programs. 

When you use the LOAD and RON commands to execute a program in CMS, 
you can pass an argument list to the program on the command line.. For 
example, if you enter: 

load myprog 

start * runi proga 

the arguments *, RDNl, and PROGA are placed in a parameter list of 
doublewords and register 1 contains the address of this list when your 
program receives control. If you want to use the RON command to perform 
the load and start functions, you could enter: 

run myprog (run1 proga 

The parenthesis indicates the beginning of the argument list. 

To detect the absence of a parameter list that occurs when the LOAD 
command START option is used, your program may test the doubleword 
pointed to by register 1 for a delimiter made up of 1*s in all of the 
bit positions. 

Calling a CMS Command from a Program 

You can call a CMS command from a program by setting up a parameter 
list, like that shown above, and then issuing an SVC 202. The parameter 
list you set up must have doublewords that contain the parameters or 
arguments you would enter if you were entering the command from the 
terminal. For example: 

PUNCHER DS OD 

DC CL8« PUNCH' 

DC CL8»NAME« 

DC CL8«TYPE» 

DC CL8«*» 

DC CL8»(' 

DC CL8«N0H» 

DC 8X»FF« 

In your program, when you want to execute this command, you should load 
the address of the list into register 1, and issue the supervisor call 
instruction (SVC) as follows: 

LA 1, PUNCHER 

SVC 202 

DC AL4 (ERROR) 



) 
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When you issue an SVC 202, you must supply an error return address in 
the four bytes immediately after the SVC instruction. If the return code 
(register 15) contains a nonzero value after returning from the SVC 
call, control passes to the address specified. In the above example, 
control would go to the instruction at the label ERROR. 

If you want to ignore errors, you can use the sequence: 

LA 1, PUNCHER 

SVC 202 

DC AL4 (*+U) 

If you do not specify an error address, control is returned to the next 
instruction after a normal return, but if there was an error executing 
the CMS command, your program terminates execution. 

If you want to execute a CP command or an EXEC procedure from a 
program, you must use the CP and EXEC commands; for example: 

SPOOL DS OD 

DC CLS'CP' 

DC CL8»SP00L» 

DC CL8» PRINTER' 

DC CL8»CLASS» 

DC CL8»S» 

DC 8X«FF» 

EXEC DC CL8«EXEC» 

DC CL8»PFSET» 

DC 8X«FF» 

It is not possible to enter a parameter that is longer than eight 
characters this way. 

As an alternative, you can use the CMS LINEDIT macro to call a CP 
command from a program. Specify DISP=CPCOMM on the macro instruction; 



for example: '** 

LINEDIT TEXT=» SPOOL E CLASS S • , DISP=CPCOMM,DOT=NO 

On return from the execution of the LINEDIT macro instruction, register 
15 contains the return code from the CP command. 

The LINEDIT macro is described in VM/370 CMS Command and Macro 
Reference. 

Another way to execute a CP command from a program is to use the 
I DIAGNOSE x»08« instruction. For additional information on this, see 
VM/370 Sy s t e m Pr 0£r am mer j_s Guide . 



Executing Program Modules 

MODULE files, in CMS, are nonrelocatable programs. Using the GENMCD 
command, you can create a module from any program that uses OS or CHS 
macros. When you create a module, it is generated at the virtual 
storage address at which it is loaded, for example: 

load myprog 
genmod testit 

The CMS disk file, TESTIT MODULE A, that is created as a result of this 
GENMOD command, always begins execution at location X'20000», the 
beginning of the user program area- 
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March 30, 1979 

If you want to call your own program nodules using SVC 202 
instructions, you lust be careful not to execute a module that uses the 
same area of storage that your program occupies. If you want to call a 
module that executes at location X» 20000 •, you can load the calling 
program at a higher location; for example: 

load myprog (origin 30000 

As long as the MODULE file called by MYPROG is no longer than X« 10000' 
bytes, it will not overlay your program- 
Many CMS disk-resident command modules also execute in the user 
program area; if you call these commands from a program, you should load 
your program at a higher location. 



THE TRANSIENT PROGRAM AREA 

To avoid overlaying programs executing in the user program area, you can 
generate program modules to run in the CHS transient area, which is a 
two-page area of storage that is reserved for the execution of programs 
that are called for execution frequently. Many CHS commands run in this 
area, which is located at X'EOOO'. Programs that execute in this area 
run disabled. 

To generate a module to run in the transient area, use the ORIGIN 
TRANS option when you load the TEXT file into storage, then issue the 
GENMOD command: 

load myprog (origin trans 
) genmod setup (str 

Note: If a program running in the user area calls a transient routine in 
which a module was generated using the GENMOC command with the STR 
option, the user area storage pointers will be reset. This reset 
condition could cause errors upon return to the original program (for 
example, when OS GETMAIN/FREEHAIN macros are issued in the user 
program) . 

The two restrictions placed on command modules executing in the 
transient area are: 

1. They may have a maximum size of 8192 bytes, since that is the size 
of the transient area. This size includes any free storage acquired 
by GETMAIN macros. 

2. They must be serially reusable- When a program is called by an SVC 
202, if it has already been loaded into the transient area, it is 
not reloaded. 

The CMS commands that execute in the transient area are: ACCESS, 
ASSGN, COMPARE, DISK, DLBL, FILEDEF, GENDIRT, GLOBAL, LISTFILE, HODHAP, 
OPTION, PRINT, PUNCH, QUERY, READCARD, RELEASE, RENAME, SET, SVCTRACE, 
SYNONYM, TAPE, and TYPE. 

CMS Macro Instructions 

There are a number of assembler language macros distributed with the CHS 

I system that you can use when you are writing programs to execute in the 

CMS environment. They are in the macro library CMSLIB HACLIB, which is 
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normally located on the system disk. To allow for proper macro 
expansion in a system supporting VM/370 Basic System Extensions (Program 
NO. 5748-XX8) , DMSB20 MACLIB must be used in addition to CMSLIB MACLIE. 
There are macros to manipulate CMS disk files, to handle terminal 
communications, to manipulate unit record and tape input/output, and to 
trap interruptions. These macros are discussed in general terms here; 
for complete format descriptions, see VH/370 CMS Command and Macro 
Reference. 



MACROS FOR DISK FILE MANIPULATION 



Disk files are described in CMS by means of a file system control block 
(FSCB) . The CMS macro instructions that manipulate disk files use FSCBs 
to identify and describe the files. When you want to manipulate a CMS 
file, you can refer to the file either by its file identifier, 
specifying 'filename filetype filemode* in quotation marks, or you can 
refer to the FSCB for the file, specifying FSCB=fscbr where fscb is the 
label on an FSCB macro. 



To establish an FSCB for a file, you can use 
instruction specifying a file identifier; for example: 



INFILE 



FSCB 'INPUT TEST A1' 



the FSCB macro 



You can also provide, on the FSCB macro instruction, descriptive 
information to be used by the input and output macros. If you do not 
code an FSCB macro instruction for a file, an FSCB is created inline 
(following the macro instruction) when you code an FSREAD, FSWRITE, or 
FSOPEN macro instruction. 



The format of an FSCB is listed below, followed by 
each of the fields. 



a description of 



5§scrijgtion 

File system command 

Filename 

Filetype 

Filemode 

Relative record number (RECNO) 

Address of buffer (BUFFER) 

Number of bytes to read or write (BSIZE) 

Record format - F or V (RECFM) 

Flag byte 

Number of records to read or write (NOREC) 

Number of bytes actually read 

Extended FSCB relative record number 

Extended FSCB relative number of records 

Extended FSCB relative write pointer 

Extended FSCB relative read pointer 

The fields FSCBAITN, FSCBANIT, FSCBWPTR, and FSCERPTR are only generated 
in the FSCB when the extended format FSCB is requested (FORM=E is coded 
on the FSCB macro instruction). In this case, the fields FSCBITNO and 
FSCBNOIT are reserved fields. Extended format FSCBs must be used to 
manipulate files larger than 65,533 items. 

The labels shown above are not generated by the FSCB macro; to reference 
fields within the FSCB by these labels, you must use the FSCBD macro 
instruction to generate a DSECT. 



Label 






FSCBCOMM 


DC 


CL8« • 


FSCBFN 


DC 


CL8« • 


FSCBFT 


DC 


CL8' ' 


FSCBFM 


DC 


CL2' • 


FSCBITNO 


DC 


H'O' 


FSCBBUFF 


DC 


A«0» 


FSCBSIZE 


DC 


F»0« 


FSCBFV 


DC 


CL2«F» 


FSCBFLG 


EQU 


FSCBFY+I 


FSCBNOIT 


DC 


H«1' 


FSCBNORD 


DC 


AL4 (0) 


FSCBAITN 


DC 


AL4 (0) 


FSCBANIT 


DC 


AL4 (1) 


FSCBWPTR 


DC 


AL4 (0) 


FSCBRPTR 


DC 


AL4 (0) 
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FSCBCOMMl When the FSCBFN, FSCBFT, and FSCBFM fields are filled in, ycu 
can fill in the FSCBCOMM field with the name of a CMS command and use 
the FSCB as a parameter list for an SVC 202 instruction. (You must 
place a delimiter to mark the end of the command line.) 

I^QMIlr ZSCBFT, FSCBFM: The filename, filetype and filemode fields 
identify the CMS file to be read or written- You can code the fileid en 
a macro line in the format •filename filetype filemode* or you can use 
register notation. If you use register notation, the register that you 
specify must point to an 18-byte field in the format: 

FILEID DC CL8 •filename* 
DC CL8* filetype* 
DC CL2»fm' 
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The fileid must be specified either in the FSCB for a file or on the 
FSREAD, FSWRITE, FSOPEN, or FSERASE macro instruction you use that 
references the file. 

\ FSCBITHO; For an FSCB without the FORM=E option, the record or item 
number indicates the relative record number of the next record to be 
read or written; it can be changed with the RECWO option. The default 
value for this field is 0. When you are reading files, a indicates 
that records are to be read sequentially, beginning with the first 
record in the file. When you are writing files, a indicates that 
records are to be written sequentially, beginning at the first record 
following the end of the file, if the file already exists, or with 
record 1, if it is a new file. 

I For an FSCB generated with the FORM=E option, the FSCBAITN field 
I contains the record or item number. The FSCBITNO field is reserved. 

Whenever you read discontiguous files in CMS (that is, files with 
missing records) , the input buffer will be filled with the appropriate 
number of bytes. Be aware that the flag byte in the FSCB may not 
reflect whether the input buffer contains generated data items frop 
RDBOF. 

FSCBBOFF; The buffer address, specified in the EDFFER option, indicates 
the label of the buffer from which the record is to be written or into 
which the record is to be read. You should always supply a buffer large 
enough to accommodate the longest record you expect to read or write. 
This field must be specified, either in the FSCB, or on the FSREAD or 
FSWRITE macro instruction. 

FSCBSIZE: This field indicates the number of bytes that are read or 
written with each read or write operation. The default value is 0. If 
the buffer that you use represents the full length of the records you 
are going to be reading or writing, you can use the BSIZE option to set 
this field equal to your buffer length; when you are writing 
variable-length records, use the BSIZE operand to indicate the length of 
each record you write. This field must be specified. 

FSCBFV: This two-character field indicates the record format (RECFM) of 
the file. The default value is F (fixed) . 

I FSCBFLG; The flag byte is X*20« indicating an extended FSCB generated 
I when the FORM=E option is coded on the FSCB macro instruction. 

I FSCBNOIT: For an FSCB without the FORM=E option, this field contains the 
number of whole records that are to be read or written in each read or 
write operation. You can use the NOREC option with the BSIZE option to 
block and deblock records. The default value is 1. 

I For an FSCB generated with the FORM=E option, the FSCBANIT field 
I contains the number of whole records to be read or written. The 
I FSCBNOIT field is reserved. 

FSCBNORD: Following a read operation, this field contains the number of 
bytes that were actually read, so that if you are reading a 
variable-length file, you can determine the size of the last record 
read. The FSREAD macro instruction places the information from this 
field into register 0. 

I FSCBAITN: The alternate record or item number indicates the relative 

j record number of the next record to be read or written in an extended 

I FSCB format. See the description of the FSCBITNO field for the usage of 

I this field. 
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fSCBANIT: This field contains the alternate nunber of whole records in 
an extended FSCB format. See the description of the FSCBNOIT field for 
the usage of this field. 

FSCBWPTR; The FSPOINT macro instruction uses this field to contain the 
alternate write pointer for an extended FSCB during a POINT operation. 

FSCBRPTR; The FSPOINT macro instruction uses this field to contain the 
alternate rfead pointer for an extended FSCB during a POINT operation. 

Dsinq the FSCB 

The following example shows how you might code an FSCB macro instruction 
to define various file and buffer charaqteristics, and then use the same 
FSCB to refer to different files: 

I FSREAD 'INPUT FILE A1«,FSCB=C0MM0N,F0RB-E 

I FSWRITE • OUTPUT FILE Al • ,FSCB=COHMON,FORH=E 



COMMON FSCB BUFFER=SHaRE,RECFM=V, BSIZE=2C0,FORM=E 
SHARE DS CL200 

In the above example, the fileid specifications on the FSREAD and 
FSHRITE macro instructions modify the FSCB at the label COMMON each time 
a read or write operation is performed. You can also modify an FSCB 
directly by referring to fields by a displacement off the beginning of 
the FSCB; for example: 

MVC FSCB-l-8,=CL8»NEWNAME» 

moves the name NEWNAME into the filename field of the FSCB at the label 
FSCBFN. 

As an alternative, you can use the FSCBD macro instruction to 
generate a DSECT and refer to the labels in the DSECT to modify the 
FSCB? for example: 

LA R5,INFSCB 
USING FSCBD, R5 

MVC FSCBFN, NEWNAME 

INFSCB FSCB 'INPUT TEST Al'>FORM=E 
NEWNAME DC CL8 'OUTPUT* 
FSCBD 

In the above example, the MVC instruction places the filename OUTPUT 
into the FSCBFN (filename) field of the FSCB. The next time this FSCB is 
referenced, the file OUTPUT TEST is the file that is manipulated. 



1j§1^1J3£[ 5fiJ liiiiM CMS Disk Files 

CMS disk files are seguential files; when you use CHS macros to read and 
write these files, you can access them sequentially with the FSREAD and 
FSWRITE macros. However, you may also refer to records in a CHS file by 
their relative record numbers, so you can, in effect, access records 
using a direct access method. 
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If you know which record you want to read or write, you can specify 
the REGNO option on the FSCB macro instruction, or on the FSOPEM, 
FSREAD, or FSHRITE macro instructions. When you use the REGNO option on 
the FSGB macro instruction, you must specify it as a self-defining term; 
for the FSOPEN, FSREAD, or FSWRITE macro instructions, you may specify 
either a self-defining term, as: 

I WRITE FSWRITE FSGB=WFSGB,REGNO=10, FORM=E 

or using register notation, as follows: 
I WRITE FSWRITE FSCB=WFSCB,RECNO= (5) ,FORM=E 

Where register 5 contains the record number of the record to be read. 

When you want to access files sequentially, the FSCBITNO field of the 

I FSCB must be for an FSGB without the FOR!!=E option; for an extended 

i FSGB, the FSGBAITN field must be 0. This is the default value. When you 

are reading files with the FSREAD macro instruction, reading begins with 

record number 1. When you are writing records to an existing file with 

the FSWRITE macro, writing begins following the last record in the file. 

To begin reading or writing files sequentially beginning at a 
specific record number, you must specify the REGNO option twice: once to 
specify the relative record number at which you want to begin reading, 
and a second time to specify REGNO=0 so that reading or writing will 
continue sequentially beginning after the record just read or written. 
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You can specify the REGNO option on the FSREAD or FSWRITE nacro 
I instruction, or you may change the FSCBITNO or FSCBAITN field in the 
I FSCB for the file, as necessary for the FSCB fori. 

For example, to read the first record and then the 50th record of a 
file, you could code the following: 

I READ1 FSREAD FSCB=RFSCB,FORH=E 
I FSHRITE FSCB=WFSCB,FORM=E 

LA 5,RFSCB 
I USING FSCBD,5 

I MVC FSCBAITN, =F«50» 

I READ50 FSREAD FSCB=RFSCB,FORM=E 
I FSWRITE FSCB=WFSCB,FORM=E 



RFSCB FSCB 'INPUT FILE Al« ,BUFFER=COMMON,BSIZE=120,FORH=E 
WFSCB FSCB 'OUTPUT FILE Al • ,BUFFER=COMMON,BSIZE=120,FOHM=E 
COMMON DS CL120 



FSCBD 

In this example, the statements at the label READ1 write record 1 from 
the file INPUT FILE Al to the file OUTPUT FILE Al. Then, using the 
DSECT generated by the FSCBD macro, the FSCEAITN field is changed 
because an extended FSCB is being used and record 50 is read from the 
input file and written into the output file. 

IJADING AND WRITING YARIABLE^LENGTH RECORDS; When you read or write 
variable-length records, you""must''specIfy RECFH=V either in the FSCB for 
the file or on the FSWRITE or FSREAD macro instruction. The read/write 
buffer should be large enough to accommodate the largest record you are 
going to read or write. 

To write variable- length records, use the BSIZE= option on the 
FSWRITE macro instruction to indicate the record length for each record 
you write. When you read variable-length records, register contains, 
on return from FSREAD, the length of the record read. 

The following example shows how you could read and write a 
variable-length file: 

READ FSREAD 'DATA CHECK Al • ,BOFFER=SHARI,BSIZE=130,ERHOR=OUT, 
FORM=E 
FSWRITE 'COPY DATA Al • ,BUFFER=SHARE,BSIZE- (0) ,FORM=E 
B READ 



End-gf-File Checking 



You can specify the ERROR= operand with the FSREAD or FSWRITE macro 
instruction, so that an error handling routine receives control in case 
of an error. In CHS, when an end of file occurs during a read request, 
it is treated as an error condition. The return code is always 12. If 
you specify an error handling routine on the FSREAD macro instruction, 
then the first thing this routine can do is check for a 12 in register 
15. 

Your error handling routine may also check for other types of errors. 
See the macro description in VM^370 CMS Command and Macro Reference for 
details on the possible errors and the associated return codes. 
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GP®SiS3 arid C 1 os ina Files 



Usually, CMS opens a file whenever an FSBEAD or FSWRITE macro 
instruction is issued for the file. When control returns to CMS from a 
calling program, all open files are closed by CMS, so you do not have to 
close files at the end of a program. 

For a minidisk in 1K-, 2K-, or UK-byte block format, a file may be 
open for concurrent read and write operations, and an FSCLOSE need not 
be issued when switching from reading to writing, or vice versa. For 
example: 



READ 



LA 3,2 

FSREAD FSCB=0PDATE,RECN0=(3) ,ERROR=READERR,FORM= 



FSWRITE FSCB=DPDATE,RECN0=(3) , ERROR=WRITEHR,FORM=E 
LA 3,1(3) 
B READ 



UPDATE 



FSCB 'UPDATE FILE Al ' , BUFFER=BUF1 ,BSIZE=80,FORM=E 



However, if you want to read and write records from the same file on 

an 800-byte block format minidisk, you must issue an FSCLOSE macro 

instruction to close the file whenever you switch from reading to 
writing. For example: 

LA 3,2 
READ FSREAD FSCB=UPDATE,RECNO= (3) ,ERROR=READERR 
FSCLOSE FSCB=UPDATE 



FSWRITE FSCB=UPDATE,RECNO= (3) , ERROH=WRITERR 
FSCLOSE FSCB=UPDATE 
LA 3,1(3) 
B READ 



UPDATE 



FSCB 'UPDATE FILE A1 » ,BUFFER=BUF1 ,BSIZE=80 



To execute a loop to read, update, and rewrit 
a record, close the file, write a record, clos 
Since closing a file repositions the read poin 
the file and the write pointer at the end of th 
the relative record number (RECNO) for each read 
the above example, register 3 is used to cont 
number. It is initialized to begin reading wi 
the file and is increased by one following each 



e records, you must read 
e the file, and so on. 
ter to the beginning of 
e file, you must specify 
and write operation. In 
ain the relative record 
th the second record in 
write operation. 



When you use an EXEC to execute a program to read or write a file, 
the file is not closed by CMS until the EXEC completes execution. 
Therefore, if you read or write the same file more than once during the 
EXEC procedure, you must use an FSCLOSE macro instruction to close the 
file after using it in each program, or use the FSOPEN macro instruction 
to open it before each use. Otherwise, the read or write pointer is 
positioned as it was when the previous program completed execution. 
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CREATING NES IllilS: When you want to begin writing a new file using CBS 
data management macros, there are two ways to ensure that the file you 
want to create does not already exist. One way is to issue the FSSTATE 
macro instruction to verify the existence of the file. 

A second way to ensure that a file does not already exist is to issue 
an FSERASE macro instruction to erase the file. If the file does not 
exist, register 15 returns with a code of 28. If the file does exist, it 
is erased. 

Figure 21 illustrates a sample program using CMS data management 
macros. 
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LINE SOURCE STATEMENT 

BEGIN CSECT 1 
PRINT NOGEN 

OSING *,12 ESTABLISH ADDRESSABILITY 

LR 12,15 
ST 1U,SA?E 

LA 2,8 (,1) R2=ADDR OF INPUT FILEID IN PLIST 
LA 3,32 (,1) R3=ADDR OF OUTPUT FILEID IN PLIST 

* DETERMINE IF INPUT FILE EXISTS 

FSSTATE (2) ,EHR0R=ERR1,F0RM=E 
* 

* READ A RECORD FROM INPUT FILE AND WRITE ON OUTPUT FILE 
RD FSREAD (2) ,ERROR=EOF,BUFFER=BUFF1,BSIZE=80,FORM=E 

FSWRITE (3) ,ERROR=ERR2,BUFFER=BUFF1,BSIZE=80,FORM=E 
B RD LOOP BACK FOR NEXT RECORD 

* 

* COME HERE IF ERROR READING INPUT FILE 

EOF C 15,=FM2» END OF FILE ? M 
BNE ERR3 ERROR IF NOT 

LA 15,0 ALL O.K. - ZERO OUT R15 

B EXIT GO EXIT 

* IF INPUT FILE DOES NOT EXIST 

ERR1 HRTERM 'FILE NOT FOUND* ,EDIT=YES 
B EXIT 

* IF ERROR WRITING FILE 

ERR2 LR 10,15 SAVE RET CODE IN REG 10 5 



LINEDIT TEXT= 'ERROR CODE 
B EXIT 



IN WRITING FILE«,SUB=(DEC, (10)) 



* IF READING ERROR WAS NOT NORMAL END OF FILE 



ERR3 



LR 



10,15 



SA¥E RET CODE IN REG 10 



LINEDIT TEXT=»ERROR CODE 



IN READING FILE* , SUB= (DEC, (10) ) 



♦ 






EXIT 


L 


14, SAVE 




BR 


1U 


* 






BUFFI 


DS 


CL80 


SAVE 


DS 
END 


F 



LOAD RETURN ADDRESS 
RETURN TO CALLER 



Notes; 

1 The program night be invoked with a parameter list in the format 
prognane INPUT FILE Al OUTPUT FILE Al. This line is placed in a 
parameter list by CMS routines and addressed by register 1 

(see note 2). 

2 The parameter list is a series of doablevords, each containing 
one of the words entered on the command line. Thus, 8 bytes 
past register 1 is the beginning of the input fileid; 2U bytes 
beyond that is the beginning of the second fileid. 

3 The FSREAD and FSWRITE macros cause the files to be opened; no 
open macro is necessary. CMS routines close all open files when 
a program completes execution. 

4 The return code in register 15 is tested for the value 12, 
which indicates an end— of— file condition. If it is the end of 
the file, the program exits; otherwise, it writes an error 
message. 

5 The dots in the LINEDIT macro are substituted, during execution, 
with the decimal value in register 10. 

K. ■ ^-— 

Figure 21. A Sample Listing of a Program that Uses CMS Macros 
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CMS MACROS FOR TERMINAL COMMUNICATIONS 



There are four CMS macros you can use to write interactive, 
terminal-oriented programs- They are RDTERM, WRTERM, LINEDIT, and WAITT. 
RDTERM and WRTERM Only require a read/write buffer for sending and 
receiving lines from the terminal. The third, LINEDIT, has a 
substitution and translation capability. 

When you use the WRTERM macro to Write a line to your terminal you 
can specify the actual text line in the macro instruction, for example: 

DISPLAY WRTERM 'GOOD MORNING* 

You can also specify the message text by referring to a buffer that 
contains the message. 

The RDTERM macro accepts a line from the terminal and reads it into a 
buffer you specify. You could use the RDTERM and WRTERM macros together, 
as follows: 



WRITE 


WRTERM 


•ENTER LINE» 


READ 


RDTERM 


BUFFER 




LR 3, 


rO 


REWRITE 


WRTERM 


BUFFER, (3) 



BUFFER 



DS 



CL130 



In this example, the WRTERM macro results in a prompting message. Then 
the RDTERM macro accepts a line from the terminal and places it in the 
buffer BUFFER. The length of the line read, contained in register on 
return from the RDTERM macro, is saved in register 3. When you specify 
a buffer address on the WRTERM macro instruction, you must specify the 
length of the line to be written. Here, register notation is used to 
indicate that the length is contained in register 3. 

The LINEDIT macro converts decimal and hexadecimal data into EBCDIC, 
and places the converted value into a specified field in an output line. 
There are list and execute forms of the macro instruction, which you can 
use in writing reentrant code. Another option allows you to write lines 
to the offline printer. The LINEDIT macro is described, with examples, 
in VM/320 CMS Command and Macro Reference. Figure 21 shows how you 
might use the LINEDIT macro to convert and display CMS return codes. 

The WAITT (wait terminal) macro instruction can help you to 
synchronize input and output to the terminal. If you are executing a 
program that reads and writes to the terminal frequenrtly, you may want 
to issue a WAITT macro instruction to halt execution of the program 
until all terminal I/O has completed- 



CMS MACROS FOR UNIT RECORD AND TAPE I/O 



CMS provides macros to simplify reading and punching cards (RDCARD and 
PUNCHC) , and creating printer files (PRINTL) . When you use either the 
PUNCHC or PRINTL macros to write or punch output files while a program 
is executing, you should remember to issue a CLOSE command for your 
virtual printer or punch when you are finished. You can do this either 
after your program returns control to CMS, by entering: 
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cp close e 

— or — 

cp close d 

or, you can set up a parameter list with the command line CP CLOSE E or 
CP CLOSE D and issue an SVC 202. 

The tape control macros, RDTAPE, WRTAPE and TAPECTL, can read and 
write CMS files from tape, or control the positioning of a tape. 

INTERRUPTION HANDLING MACROS 

YOU can set up routines in your programs to handle interruptions caused 
by I/O devices, by SVCs, or by external interruptions using the HNDINT, 
HNDSVC, or HNDEXT macro instructions. 

With the HNDINT macro instruction, you can specify addresses that are 
to receive control when an interruption occurs for a specified device. 
If the WAIT option is used for a device specified in the HNDINT macro 
instruction, then the interruption handling routine specified for the 
device does not receive control until after the WAITD macro instruction 
is issued for the device. 

You can use the HNDSVC macro instruction to trap supervisor call 
instructions of particular numbers, if, for example, you want to perform 
some additional function before passing control or you do not want any 
SVCs of the specified number to be executed- 

The CP EXTERNAL command simulates external interruptions in your 
virtual machine; if you want to be able to pass control to a particular 
internal routine in the event of an external interruption, you can use 
the HNDEXT macro instruction. 



Updating Source Programs Using CMS 

As you test and modify programs, you may want to keep backup copies of 
the source programs. Then you can always return to a certain level of a 
program in case you have an error. CMS provides several approaches to 
the problem of program backup: the method you choose depends on the 
complexity of your project, the changes you want to make, and the size 
of your programs. 

The simplest method is to make a copy of the current source file 
under a new name. You can do this using either the COPYFILE command or 
the CMS editor. If you use the COPYFILE command, your command line 
might be: 

copyfile account assemble a oldacct assemble a 

Then, you can use the editor to modify ACCOUNT ASSEMBLE; the file 
OLDACCT ASSEMBLE contains your original source file. 

You can make a copy of your source file using the CMS editor 
directly. For example, if you issue: 

edit account assemble 

EDIT: 

f name newacct 
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then any subsequent changes you make to the file ACCOUNT ASSEMBLE are 
written into the file NEWACCT ASSEMBLE. When you issue a FILE or SAVE 
subcommand, your source file remains intact- 
After your changes to the source program have been tested you can 
replace the source file with your new copy. 



THE UPDATE PHILOSOPHY 

While the procedures outlined above for modifying programs are suitable 
for many applications, they may not be adequate in a situation where 
several programmers are applying changes to the same source code. These 
procedures also have the drawback of not providing you with a record of 
what has been changed- After using the editor, you do not have a record 
of the lines that have been deleted, added, replaced, and so on, unless 
you manually add comments to the code, insert special characters in the 
serialization column, or use some technique that records program 
activity. 

The UPDATE command provides a way for you to modify a source program 
without affecting the original, and it produces an update log, 
indicating the changes that have been made- Moreover, it also has the 
capability of combining multiple updates at one time, so that changes 
made by different programmers or changes made at different times can be 
combined into a single output file- 

The UPDATE command is a basic element of the entire VM/370 updating 
scheme and is used by system programmers who maintain VM/370 at your 
installation- Although the input filetypes used by the UPDATE command 
default to ASSEMBLE file characteristics, the UPDATE command is not 
limited to assembler language programs, nor is it limited to system 
programming applications. You can use it to modify and update any 
fixed-length, 80-character file that does not have data in columns 72 
through 80- 



UPDATE FILES 

A simple update involves two input files: 

• The source file, which is the program you want to update 

• An update file, containing control statements that describe the 
changes you want to make 

The control statement file usually has a filetype of UPDATE- For 
convenience, you can give it the same filename as your source file- For 
example, if you want to update the file SAMPLE ASSEMBLE, you would 
create a file named SAMPLE UPDATE. 

To apply the changes in the update file, you issue the command: 

update sample 

The default values used by the UPDATE command are filetypes of ASSEMBLE 

and UPDATE for the source and update files, respectively. If you are 

updating a COBOL source program named READY COBOL with an update file 
named UPDATE READY, you would issue the command: 

update ready cobol a update ready a 
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After an UPDATE command completes processing, the input files are not 
changed; two new files are created. One of them contains the updated 
source file, with a filename that is the same as the original source 
file but preceded by a dollar sign ($) . Another file, containing a 
record of updates is also created; it has a filename that is the same as 
the source file and a filetype of OPDLOG. For example: 



Source files 
SAMPLE ASSEMBLE 
SAMPLE OPDATE 



Out£ut files 
$SAMPLE ASSEMBLE 
SAMPLE OPDLOG 



READY COBOL 
OPDATE READY 



$READY COBOL 
READY OPDLOG 



Now, you can assemble or compile the 
OPDATE command. 



new source file created by the 



OPDATE Control Statements 



The control statements used by the UPDATE command are similar to those 
used by the OS lEBOPDTE utility program or the EOS MAIUT program OPDATE 
function. 

Each OPDATE statement must have the characters ./ in columns one and 
two, followed by one or more blanks. The statements are described 
below, with examples. 

SEQOENCE Statement: This statement tells the OPDATE command that you 
want to number or renumber the records in a file. Sequence numbers are 
written in columns 73 through 80. For example, the statement: 

./ S 1000 

indicates that you want sequence numbering to be done, in increments of 
1000, with the first statement numbered 1000. The SEQOENCE statement is 
convenient if you want to apply updates to a file that does not already 
have sequence numbers. In this case, you may want to use the REP 
(replace) option of the OPDATE command, so that instead of creating a 
new file (Sfilename) , the original source file is replaced: 

update sample (rep 

INSERT Statement: This statement precedes new records that you want to 
add to a source file. The INSERT statement tells the OPDATE command 
where to add the new records. For example, the lines: 



./ I 1600 
TEST2 TM 
BNO 



HOLIDAY, X»02« 
VACATION 



HOLIDAY? 
NOPE... VACATION 



result in the two lines of code being inserted into the output file 
following the statement numbered 00001600. The inserted lines are 
flagged with asterisks in columns 73 through 80. The INSERT statement 
also allows you to request that new statements be sequenced; see 
"Sequencing Output Records." 



) 



DELETE Statement: This statement tells the OPDATE command which records 
you want to delete from the source file. If your OPDATE file contains: 

./ D 2500 
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then only the record 00002500 is deleted. If the file contains 

./ D 2500 2800 

then all the statenents from 2500 through 2800 are deleted from the 
source file. 

REPLACE Statement: The REPLACE statement allows you to replace one or 
more records in the source file. It precedes the new records you want 
to add. It is a combination of the DELETE and INSERT statements. For 
example, the lines 

./ R 38000 38500 

PLIST DS OD 

DC CL8»TYPE» 

DC CL8« • 

DC CL8'FILE» 

DC CLS'AV 

DC 8X»FF« 

replace existing statements numbered 38000 through 38500 with the new 
lines of code. As with the INSERT statement, new lines are not 
automatically resequenced. 

COMMENT Statement; Use this statement when you want to place comments in 
the update log file. For example, the line: 

-/ * Changes by John J. Programmer 

is not processed by the UPDATE command when it creates the new source 
file, but it is written into the update log file. 

SEQUENCING OUTPUT RECORDS 

The UPDATE command expects source files to have sequence numbers in 
columns 73 through 80. If you use the SERIAL subcommand of the CMS 
editor to sequence your files, the sequence numbers are usually written 
in columns 76 through 80; columns 73 through 75 contain a 
three-character identifier which is usually the first three characters 
of the filename. If you want an eight-character sequence number, you 
must use the subcommand: 

serial all 

prior to issuing a FILE or SAVE subcommand when you are editing the 
file. Or, you can create an UPDATE file with the single record: 

./ S 

and issue the UPDATE command to sequence the file. 

If you use the UPDATE command with a file that has been sequenced 
using the CMS editor's default values, you must use the N0SEQ8 option- 
Otherwise, the UPDATE command cannot process your input file. The 
command: 

update sample (noseq8 

tells UPDATE to use only columns 76 through 80 when it looks for 
sequence numbers. 

Figure 22 shows the four files involved in a simple update, and their 
contents. 
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The Source File, SAMPLE ASSEMBLE 



SAMPLE CSECT 

OSIHG SAMPLE, R12 

LR R12,R15 

ST R1'»,SAVRET 

LINEDIT TEXT=«PLEASE ENTER YOOR NAME' 

RDTERM NAME 

LINEDIT TEXT='PLEASE ENTER YOOR AGE' 

RDTERM AGE 

LINEDIT TEXT='HI, , YOD JDST TOLD ME YOD ARE 

SDB= (CHARA, NAME, CHARA, AGE) ,RENT=NO 





L Ria,SA 




BR Ria 




EJECT 


NAME 


DC CL130' 


AGE 


DC CL130' 


SAVRET 


DC F'0« 




REGEQO 




END 



00000100 
00000200 
00000300 

oooooaoo 

00000500 
00000600 
00000700 
00000800 
,x00000900 
00001000 
00001100 
00001200 
00001300 
00001400 
00001500 
00001600 
00001700 
00001800 



The update File, SAMPLE OPDATE 



I 



./ * REVISION BY DLC 
./ R 500 

LINEDIT TEXT=»WHAT"S YOUR NAME? ' ,DOT=NO 
./ R 700 1000 

LINEDIT TEXT='HI, , ENTER THE DOCNAME', 

SUB= (CHARA, NAME) 

RDTERM NAME 

MVC DOCFN,NAME 

LA 1,PLIST 

SVC 202 

DC AL4 (ERROR) 
RETURN EQU * 
./ I 1200 
ERROR EQU * 

iRTERM 'FILE NOT FOUND' 



B 



./ D 1500 
./ I 1600 
PLIST 



DOC FN 



DS 
DC 
DC 
DC 
DC 
DC 



RETURN 



OD 

CLS'TYPE' 

CL8« • 

CL8'FILE' 

CL8'A1' 

SX'FF' 



SAM00010 
SAM00020 
SAM00030 
SAM00040 
XSAM00050 
SAM00060 
SAM00070 
SAM00080 
SAM00090 
SAM00100 
SAM00110 
SAM00120 
SAM00130 
SAM001U0 
SAM00150 
SAM00160 
SAM00170 
SAM00180 
SAM00190 
SAH00200 
SAM00210 
SAM00220 
SAM00230 
SAM00240 



Figure 22. Updating Source Files with the UPDATE Command (Part 1 of 2) 



) 
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The update Log File, SAMPLE UPDLOG 



OPDATING •SAMPLE ASSEMBLE Al« WITH "SAMPLE 
./ * REVISION BY DLC 
./ R 500 



DPDATE 



AT 



UPDATE LOG — PAGE 



11 



DELETING... 
INSERTING... 

./ R 700 1000 
DELETING... 



INSERTING... 



RETURN 
./ I 1200 
INSERTING ERROR 



LIHEDIT TEXT=» PLEASE ENTER YOUR NABE» 
LINEDIT TBXT='WHAT« 'S YOUR NAME?' ,DOT=NO 

LINEDIT TEXT='PLEASE ENTER YOUR AGE» 

RDTERM AGE 

LINEDIT TEXT=»HI, , YOU JUST TOLD BE YOU ARE 

SUB=(CHARA, NAME, CHARA, AGE) ,RENT=NO 
LINEDIT TEXT=»HI, , ENTER THE DOCNABE» , 

SUB=(CHARA,NAME) 
RDTERM NAME 
MVC DOCFN,NAME 
LA 1,PLIST 
SVC 202 

DC AL4 (ERROR) 
EQU * 

EQU * 

WRTERM 'FILE NOT FOUND' 





B 


RETURN 


./ D 1500 






DELETING... AGE 


DC 


CL130' • 


./ I 1600 






INSERTING... PLIST 


DS 


OD 




DC 


CL8'TYPE' 


DOCFN 


DC 


CL8» ' 




DC 


CL8'FILE' 




DC 


CL8'A1' 




DC 


8X'FF' 



000005001 

I 

000007001 

000008001 

,x00000900| 

000010001 

I 
I 

00001500! 

I 



The updated Output File, $SAMPLE ASSEMBLE 



1 SAMPLE 


CSECT 






USING SAMPLE, R12 






LR R12,R15 






ST RIU, SAVRET 






LINEDIT TEXT='WHAT"S YOUR 


NAME?»,DOT=NO 




RDTERM NAME 






LINEDIT TEXT='HI, 


,. , ENTER THE DOCNAME', 




S0B=(CHARA,NAME) 






RDTERM NAME 






MVC DOCFN, NAME 






LA 1, PLIST 






SVC 202 






DC AL4 (ERROR) 




1 RETURN 


EQU * 

L Ria, SAVRET 

BR R14 




1 ERROR 


EQU * 

WRTERM 'FILE NOT FOUND' 

B RETURN 

EJECT 




1 NAME 


DC CL130' • 




1 SAVRET 


DC F'O' 




1 PLIST 


DS OD 

DC CL8'TYPE' 




1 DOCFN 


DC CL8» • 
DC CL8'FILE' 
DC CL8'A1» 
DC 8X»FF» 
REGEQU 
END 





000001001 
000002001 
000003001 
000004001 

000006001 

000011001 
000012001 

000013001 
000014001 
000016001 

itc*******[ 
000017001 

000018001 



Figure 22. Updating Source Files with the UPDATE Command (Part 2 of 2) 
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The INSERT and REPLACE statements allow you to control the numbering 
increment of records that you add to a source file. Notice, in Figure 
22, that inserted records have the character string «********t in 
columns 73 through 80. If you want sequence numbers on the inserted 
records, you must do two things: 

1. Ose the INC option on the UPDATE command line. If you use the CTL 
option, you do not have to specify the INC option. The CTL option 
is described below, under "Multiple Updates." 

2. Include a dollar sign ($) on the INSERT or REPLACE statement, 
optionally followed by operands indicating how the records should 
be sequenced. 

For example, to sequence the records added in Figure 22, the control 
statements would appear as: 

./ R 500 $ 

./ R 700 1000 $ 

./ I 1200 $ 

./ I 1600 $ 

and you would issue the UPDATE command: 

update sample (inc 

The UPDATE command sequences inserted records by increments of 10. 
If you want to control the numbering, for example, if you need to insert 
more than 10 statements between two existing statements, you can specify 
an alternate sequencing scheme: 

./ I 1800 $ 1805 5 



Records introduced following this INSERT statement are numbered 
00001805, 00001810, 00001815, and so on, (If the N0SEQ8 option is in 
effect, then the records would be XXX01805, XXX01810, and so on, where 
XXX is the three-character identifier used in columns 73 through 75.) 



MULTIPLE UPDATES 

If you have several UPDATE files to apply to the same source, you may 
apply them in a series of UPDATE commands. For example, if you have 
updates named FICA UPDTUPl, FICA UPDTUP2, and FICA UPDTUP3 to apply to 
the source file FICA PLIOPT, you could do the following: 

1. Update the source file with TESTI UPDATE: 

update fica pliopt a fica updtupl 

2. Update the source file produced by the above command with the TEST2 
UPDATE: 

update $fica pliopt a fica updtup2 

3. Update the new source file with TEST3: 

update $$fica pliopt a fica updtup3 
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This final UPDATE command produces the file $$$FICA PLIOPT, which is now 
the fully updated source file. This method is cumbersome, however, 
particularly if you have many updates to apply and they must be applied 
in a particular order. Therefore, the UPDATE command provides a 
multilevel update scheme, which you can use to apply many updates at one 
time, in a specified order. 

To apply multilevel updates, you must have a control file, which by 

convention has a filetype of CNTRL and a filename that is the same as 

the source input file. Therefore, to apply the three update files to 
PICA PLIOPT, you should create a file named PICA CNTRL. 



The Control File 

A control file is actually a list: it does not contain any actual update 
control statements (INSERT, DELETE, and so on) , but rather it indicates 
what update files should be applied, and in what order. In the case of 
a multilevel update, all the update files must have the same filename as 
the source file. Therefore, only the filetypes need be specified in the 
control file to uniquely identify the update file. In fact, if all your 
update files have filetypes beginning with the characters UPDT, you need 
only specify the unique part of the filetype. The control file for PICA 
PLIOPT, named FICA CNTRL, may typically look like the following: 

TEXT MACS PLILIB 
FICA3 UP3 
FICA2 UP2 
FICAl UP1 

The first record in the control file must be a MACS record. The 
second field in this record must be "MACS," and it may be followed by up 
to eight macro library names- Every record in the control file must ^ 
have an "update level identifier;" in this example, the update level 
identifiers are TEXT on the MACS record, FICA1 for the 0P1 record, and 
so on. The update level identifier may have a maximum of five 
characters. 

The UPDATE command only uses the MACS record and the update level 
identifier under special circumstances. These are described later, 
under "VMFASM EXEC Procedure." For now, you only need to know that 
these things must be in a control file in order for the UPDATE command 
to execute properly. 

To update FICA PLIOPT, then, you would issue the UPDATE command as 
follows: 

update fica pliopt (ctl 

When you use the CTL option, and you do not specify the name of a 
control file, the UPDATE command looks for a control file with the 
filetype of CNTRL and a filename that is the same as the source file. 
From the control file, it reads the filetypes of the updates to be 
applied. In this example, it searches for the file FICA UPDTUP1 and if 
found, applies the updates; then UPDATE searches for FICA UPDTUP2, and 
applies those updates, if any. Last it searches for FICA UPDTDP3, and 
applies those updates. 

Notice that the updates are applied from the bottom of the control 
file, toward the top. This becomes important when an update is 
dependent on a previous update. For example, if you add some lines to a 
file in FICA UPDTDPl, then modify one of those lines in FICA UPDTUP2, it 
is important that UPDTUPl was applied first. 
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ALTERNATE HAYS QF SPECIFYING MULTILEVEL UPDATE FILES: The example above, 
showing FICA CNTRL and UPDTxxxx files, illustrates a naming scheme using 
the UPDATE command defaults. You can override the default filetypes for 
the control file's filename and filetype, as well as filetypes for the 
update files. 

If you name a control file GROUPA CNTRL, for example, you can specify 
the name of the control file on the UPDATE command line: 

update fica pliopt a groupa cntrl (ctl 

Similarly, if your update files have unique filetypes, you must 
specify the entire filetype in the control file. If your updates to 
FICA PLIOPT are named FICA TESTl, FICA TEST2, and FICA TEST3, your 
control file may look like the following: 

TEXT MACS PLILIB 
,FICA3 TEST3 
FICA2 TEST2 
FICA1 TEST1 

Regardless of the filetypes you choose, however, the filenames must 
always be the same as the filename of the input source file. 



AUX Files 

The two levels of update processing shown so far may be adequate for 
your applications. There is, however, an additional level, or step, in 
the update structure that the VM/370 procedures use and which you may 
want to use also. 

These techniques may be useful when you have more than one set of 
updates to apply to a source program. For example, you may have two 
groups of programmers who are working on different sets of changes for 
the same source file. Each group may create several update files, and 
have a unique control file- When you combine these changes, you could 
create one control file, or you can use what are known as auxiliary 
control files. 

The updating structure for auxiliary control files is based on 
conventions for assigning filenames and filetypes. If a control file 
contains an entry that begins with the characters *AUX», the UPDATE 
command assumes that the file 'fn AUXnnnn' contains a list of filetypes, 
not UPDATE control statements. For example, if the file SAMPLE ASSEMBLE 
is being updated with a control file that contains the record: 

TEST1 AUXLIST 

then SAMPLE AUXLIST does not contain UPDATE control statements; it 
contains entries indicating the filetypes of the update files, all of 
which must have the same filename, SAMPLE. 

Let's expand the example to see how this structure works. We have 
the source file, SAMPLE ASSEMBLE. The file SAMPLE CNTRL contains the 
entries: 

TEXT MACS 
3676 AUXLIST 
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The file, SAMPLE AUXLIST may look like the following: 

TEST1 

FIXLOOP 

BYPASS 

The files: 

SAMPLE TEST1 
SAMPLE FIXLOOP 
SAMPLE BYPASS 

all contain UPDATE control statements (INSERT, DELETE, and so on) that 
are to be applied to the file SAMPLE ASSEMBLE. As with control file 
processing, the updates are applied from the bottom of the AOX file, so 
that the updates in SAMPLE BYPASS are applied first, then the updates in 
SAMPLE FIXLOOP, and so on. For an illustration of a set of update 
files, see Figure 23. 

Since the updating scheme uses only filetypes to uniquely identify 
update files, it is possible to use the same control file to update 
different source input files. For example, using the control file 
REPORT CNTRL shown in Figure 23, you issue the command: 

update fica pliopt a report cntrl (ctl 

The UPDATE command begins searching for updates to apply to FiCA PLIOPT, 
based on the entries in REPORT CNTRL: it searches for FICA AOXLIST, 
which may contain entries pointing to update files; then it searches for 
FICA UPDTREP1, and so on. 

As long as all updates and auxiliary files associated with a source 
file have the same filename as the source file, the updates are uniquely 
identifiable, so the same control file can be used to update various 
source files. VM/370 takes advantage of this capability in its own 
updating procedures. By maintaining strict naming conventions, updates 
to various CP and CMS modules are easily controlled and identified, 

A control file may point to many AOX files in addition to many DPDT 
files. You can modify a control file when you want to control which 
updates are applied to a program, or you may have several control files, 
and specify the name of the control file you want to use on the UPDATE 
command line. There is a lot of flexibility in the UPDATE command 
processing; you can implement procedures and conventions for your 
individual applications. 

PREFERRED LEVEL UPDATING: There may exist more than one version of an 
update, each applicable to different versions of the same module. For 
example, you may need one version of an update for an unmodified base 
source module, and another version of that update if that module has 
been modified by a program product. The AUX file that will be used to 
update a particular module must then be selected based on whether or not 
a program product modifies that module. The AUX files listing the 
updates applicable to modules modified by a program product are called 
"preferred AUX files" because they must be used if they exist rather 
than the mutually exclusive updates applicable to unmodified modules. 
Using this preferred AUX file concept, every module in a component can 
be assembled using the one CNTRL file applicable to a user's 
configuration. 

A single AUX file entry in a CNTRL file can specify more than one 
filetype. The first filetype indicates a file that UPDATE uses only on 
one condition: the files that the second and subsequent filetypes 
indicate do not exist. If they do exist, this AUX file entry is ignored 
and no updating is done. The files that the second and subsequent 
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filetypes indicate are perferred because, if they exist, UPDATE does net 

use the file that the first filetype indicates. Usually, the preferred 

files appear later in the CNTRL file in a format that causes them to be 
used for updating. 

UPDATE scans each CNTRL file entry until a preferred filetype is 
found, until there are no more filetypes on the entry, or until a 
comment is found, (A character string that is less than four or more 
than eight characters is assumed to be a comment.) 




TEXT MACS 

UP2 UPDTPROC 

LIST AUXLIST 

UP1 UPDTREP1 



TEXT AUXFIX 




update report assemble a (ctl 

UPDATING 'REPORT ASSEMBLE AT WITH 'REPORT RTNA A1' 

UPDATING WITH 'REPORT RTNB A1'. 

UPDATING WITH 'REPORT UPDTREP1 A1'. 

UPDATING WITH 'REPORT FIXOUT AT. 

UPDATINGWITH 'REPORT FIXIN AT. 

UPDATING WITH 'REPORT UPDTPROC A1 '. 

R; 



figure 23. An Update with a Control File 
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THE VMFASM EXEC PROCEDURE 

If you are an assembler language programmer and you are using the UPDATE 
command to update source programs you may want to use the VMFASM EXEC 
procedure. VMFASM is a VM/370 update procedure; it invokes the UPDATE 
command and then uses the ASSEMBLE command to assemble the updated 
source file. 

If you are not an assembler language programmer, you may wish to 
create an EXEC similar to VMFASM that, instead of calling the assembler, 
calls one of the language compilers to compile an updated source file. 

When you use VMFASM, you specify the source filename, the filename of 
the control file, and optionally, parameters for the assembler. (The 
control file for VMFASM must have a filetype of CNTRL) . For example, if 
you use the file GENERAL CNTRL to update SAMPLE ASSEMBLE, you enter the 
command line: 

vmfasm sample general 

The VMFASM EXEC uses the MACS card and the update level identifiers 

in the control file. It reads the MACS card to determine which macro 

libraries (MACLIBs) should be searched by the assembler. Then VMFASM 

issues the GLOBAL MACLIB command specifying the MACLIBs you name on the 
MACS card. 

The update level identifier is used by VMFASM to name the output text 
file produced by the assembly- If the update level identifier of the 
most recent update file (the last one located and applied) is anything 
other than TEXT, the update level identifier is prefixed with the 
characters TXT to form the filetype. For example, if the file GENERAL 
CNTRL contains the records: 

TEXT MACS CMSLIB MYLIB OSMACRO W 

UP2 FIX2 
UP1 FIX1 
TEXT AUXLIST 

and it is used to update the file SAMPLE ASSEMBLE, then: 

• If the file SAMPLE UPDTFIX2 is found and the updates applied, VMFASM 
names the output text deck SAMPLE TXTUP2. 

• If the file SAMPLE UPDTFIXI is found and the updates applied but no 
SAMPLE UPDTFIX2 is found, the text deck is named SAMPLE TXTUP1. 

• If the file SAMPLE AUXLIST is found but no SBMPLE UPDTFIXI or SAMPLE 
UPDTFIX2 files are found, the text deck is named SAMPLE TEXT. 

• If no files are found, the update level identifier on the MACS card 
is used and the text deck is named SAMPLE TEXT. 

Since the UPDATE command works from the bottom of a control file 
toward the top, it is logical that the text filename be taken from the 
identifier of the last update applied. 

The VMFASM EXEC does not produce an updated source file, but leaves 
the original source intact. VMFASM produces two output files: a printed 
output listing that shows update activity; and the text file, which 
contains the update log as well as the actual object code. If you use 
the CMS LOAD command to load a text file produced by VMFASM, records 
from the update log are flagged as invalid, but the LOAD operation is 
not impaired. 



( 
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THE STK OPTION; If you are interested in writing your own EXEC procedure 
to invoice the UPDATE command, you may wish to use the STK option. The 
STK (stack) option is valid only with the CTL option, and is meaningful 
only when the UPDATE command is invoked within an EXEC procedure- 

When the STK option is specified, UPDATE stacks the following data 
lines in the console stack: 

first line: * update level identifier 
second line: * library list from MACS record 

The update level identifier is the identifier of the most recent update 
that was found and applied. 

For example, an EXEC file that invokes the UPDATE command and then 
the ASSEMBLE command may contain the lines: 

UPDATE 81 ASSEMBLE * &2 CNTRL * (STK CTL 

&READ VARS 6STAR &TX 

&READ VARS &STAR &LIB1 &LIB2 &LIB3 &LIB4 &LIE5 SLIB6 8LIB7 8LIB8 

GLOBAL MACLIB 8LIB1 8LIB2 8LIB3 8LIB4 8LIB5 8LIB6 8LIB7 8LIB8 

8IF &TX NE TEXT FILEDEF TEXT DISK 81 TXT8TX Al 

ASSEMBLE 81 83 84 85 86 87 88 89 

ERASE $81 ASSEMBLE 

If this EXEC is named UPASM EXEC and is invoked with the line; 

upasm fica fica (print noxref 

and the file FICA CNTRL contains; 

MAC MACS CMSLIB OSMACRO MYTEST 
FIX1 UPDTFIX 
LIST AUXLIST 

then the EXEC executes the following commands: 

UPDATE FICA ASSEMBLE * FICA CNTRL * (STK CTL 
GLOBAL MACLIB CMSLIB OSMACRO MYTEST 
FILEDEF TEXT DISK FICA TXTFIX1 Al 
ASSEMBLE FICA (PRINT NOXREF 
ERASE $FICA ASSEMBLE 

The above example assumes that the update file FICA UPDTFIX was found 
and applied. 
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Part 3. Learning to Use EXEC 



In previous sections, the CMS EXEC facilities were described in general 
terms to acquaint you with the expressions used in EXEC files and the 
basic way that EXECs function. Also, examples of EXEC procedures have 
appeared throughout this publication. You should be familiar at least 
with the material in "Introduction to the EXEC Processor" before you 
attempt to use the information in Part 3. 

"Section 1U. Building EXEC Procedures" describes the EXEC facilities 
in detail, with examples of techniques you may find useful as you learn 
about EXEC and develop your own EXEC procedures. 

Special considerations for using CMS commands in EXECs and modifying 
CMS command functions using EXEC procedures are described in "Section 
15. Using EXECs With CMS Commands." 

"Section 16. Refining Your EXEC Procedures" lists several techniques 
you can use to make your EXEC files easier to use and provides some 
hints on debugging EXEC procedures. 

If you are a frequent user of the CMS editor, then you may be 
interested in "Section 17. Writing Edit Macros," which describes how to 
create your own EDIT subcommands using EXEC procedures. 
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Section 14. Building EXEC Procedures 



This section discusses various techniques that you can use when you 
write EXEC procedures. The examFles are intended only as suggestions: 
you should not feel that they represent either the only way or the best 
way to achieve a particular result. Many combinations and variations of 
control statements are possible; in most cases, there are many ways to 
do the same thing. 

This section is called "Building EXEC Procedures" because you will 
often find that once you have created an EXEC procedure and begun to use 
it, you continually think of new applications or new uses for it. Using 
the CMS editor, you may quickly build the additions and make the 
necessary changes. You are encouraged to develop EXEC procedures to help 
you in all the phases of your CMS work. 

What Is a Token? 

An executable statement is any line in an EXEC file that is processed by 
the EXEC interpreter, including: 

• CMS command lines 

• EXEC control statements 

• Assignment statements 

• Null lines 

Executable statements may appear by themselves on a line or as the 
object of another executable statement, for example in an &IF or SLOOP 
control statement. If you want to execute CP commands or other EXEC 
procedures in an EXEC, you must use the CP and EXEC commands, 
respectively. CP commands are passed directly to CP for processing. 

All executable statements in an EXEC are scanned by the CMS scan 
routine. This routine converts each word (words are delimited by blanks 
and parentheses) into an eight-character quantity called a token. If a 
word contains more than eight characters, it is truncated on the right. 
If it contains fewer than eight characters, it is padded with blanks. 
When a parenthesis appears on the line, it is treated both as a 
delimiter and as a token. For example, the line: 

STYPE WHAT IS YOUR PREFERENCE (RED | BLUE)? 

scans as follows: 

&TYPE WHAT IS YOUR PREFEREN ( RED | BLUE ) ? 

After a line has been scanned, each token is scanned for ampersands 

and substitutions are performed on any variable symbols in the tokens 

before the statement is executed. After elimination of any null 
variables, the statement may contain a maximum of 32 tokens. 

Nonexecutable statements are lines that are not processed by the EXEC 

interpreter, that is, comment lines (those that begin with an *) , and 

data lines following an 8BEGEMSG, &BEGPUNCH, 8BEGSTACK, or 8BEGTYPE 

control statement. Since these lines are not scanned, words are not 
truncated, and tokens are neither formed nor substituted. 

Since all executable statements in an EXEC are scanned, and the data 
items are treated as tokens, the term "token" is used throughout this 
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section to describe data items before and after scanning. The VM/370 
CMS command and Macro Reference, which contains the formats and 
descriptions of the EXEC control statements, uses this convention as 
well. Therefore, as you create your EXEC procedures, you may think of 
the items that you enter on an EXEC statement as tokens, since that is 
how they are used by the EXEC interpreter. 



Variables 

To make the best use of the CMS EXEC facilities, you should have an 
understanding of how the EXEC interpreter performs substitutions on 
variable symbols contained in tokens. Some examples follow. For each 
example, the input lines are shown as they would appear in an EXEC file 
and as they would appear after being interpreted and executed by EXEC. 
Notes concerning substitution follow each example. 

SIMPLE SUBSTITUTION: Most of the EXEC examples in this publication 
contain variable symbols that result in one-for-one substitution. Most 
of your variables, too, will have a similar relationship. 

Lines After Substitution 

SX = 123 &x"'= 123 

5TYPE SX STIPE 123 

The EXEC interpreter accepts the variable symbol SX and assigns it the 
value 123. In the second statement, SX is substituted with this value, 
and the control statement STYPE is recognized and executed. 

Lines After Substitution 

SY = 456 Sy"= 456 

SZ = SY SZ = 456 

The symbol SY is assigned a value of 456. In the second statement, the 
symbol SY is substituted with this value, and this value is assigned to 
SZ. 

SUBSCRIPTS FOR VARIABLES; Since each token is scanned more than once for 
ampersands, you can simulate subscripts by using two variable values in 
the same token. 

Lines After Substitution 

51 = ALPHA SI = ALPHA 

52 = BETA S2 = BETA 
SINDEX1 = 1 SINDEX1 = 1 
STYPE SSINDEX1 STYPE ALPHA 
SINDEX1 = 2 SINDEX1 = 2 
STYPE S6INDEX1 STYPE BETA 

In the statement STYPE SSINDEX1, the token SINDEX1 is scanned the first 
time, and the value SINDEX1 is substituted with the value 1. The token 
now contains SI, which is substituted with the value ALPHA on a second 
scan. When the value of SINDEX1 is changed to 2, the value of SSINDEXl 
also changes. 

Lines After Substitution 

SI =~2 SI = 2 ~ ~ ~ 

SXSI = 5 SX2 = 5 

SI = 1 SI = 1 

SXSI = 2 SX1 = 2 

SX = SXSI * SXSXSI SX = 2 + 5 
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In the statement SX&I = 5, analysis of the first token results in the 
substitution of the symbol &I with the value of 2. The symbol SX2 is 
assigned a value of 5. 



The value 
value of 2. 



of SI is changed to 1, and the symbol &X1 is assigned a 



In the last statement, 8X = SXSI + 8X&X&I, the value of 81 in the 
token 8X81 is replaced with 1, then the symbol 8X1 is substituted with 
its value, which is 2. The token 8X8X81 is substituted after each of 
three scans: 81 is replaced with the value 1, to yield the token 8X8X1. 
The symbol 8X1 has the value of 2, so the token is reduced to 8X2, which 
has a value of 5. 



COMPOUND VARIABLE SYMBOLS: Variable symbols 
character strings. 



may also be combined with 



Lines 
8X = BEE 
8TYPE H0NEY8X 
8TYPE ABDMBLE8X 



After Substitu t ion 
8X~=~BEE 
8TYPE HONEYBEE 
&TYPE ABUMBLE 



In the above example, the first symbol encountered in the scan of 
H0NEY8X is 8X, which is substituted with the value 8BEE. In the second 
8TYPE statement, the X is truncated when the line is scanned; the symbol 
8 is an undefined symbol and is therefore set to blanks. 



Lin es 

8X = HONEY 
8Y = BEE 
8TYPE &X&Y 



After Substitution 
&X''= HONEY 
8Y = BEE 
8TYPE 



In the above example, after the symbol 8Y is substituted with the value 
BEE, the token contains the symbol &XBEE, which is an undefined symbol, 
so the symbol is discarded. 



Lines 

8123 = ABCDE 
8X = 12345678 
8TYPE ABLE88X 



4fiS£ Substitution 
8123 = ABCDE" 
&X = 12345678 
8TYPE ABLEABCD 






In this example, the substitution of 8X in the token ABLE88X results in 
the character string ABLE812345678, which is truncated to eight 
characters, or ABLE8123. The scan continues, and 8123 is substituted 
with the appropriate value, to result in ABCBE. The token is again 
truncated to eight characters. 

SUBSTITUTING LITERAL VALUES; You might want an ampersand to appear in a 
token. You can use the 8LITERAL built-in function to suppress the 
substitution of variable symbols in a token. 



Lines 

89 = HELLO 

8A = 8LITERAL 89 

&TYPE 8A 



4fi§£ Substitution 
89 = HELLO 
&A = 8LITERAL 89 
8TYPE 89 



Because the value of 8A was defined as a literal 89, no substitution is 
performed- 



Lines 

8TYPE = QUERY 

8TYPE BLIP 



Mi§I Substitution 
8TYPE = query" 
QUERY BLIP 



In the above example, even though 8TYPE is an EXEC keyword, it is 
assigned the value of QUERY, and substitution is performed when it 
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appears on an input line. In this example, when it is substituted with 
its value, the result is a command line which is passed to CMS for 
processing. 

Li nes After Substitution 

6C0NTR0L = FIRST SCONTROL = FIRST" 
SLITERAL SCONTROL ALL SCONTROL ALL 

In this example, SCONTROL is assigned a value as a variable symbol, but 
when it is preceded by the built-in function SLITERAL, the substitution 
is not performed, so EXEC processes it as a control statement. 

HEXADECIMAL AN5 DECIMAL CONVERSIONS: You can perform hexadecimal to 
decimal and decimal to hexadecimal conversions in an EXEC if you use the 
control statement SHEX ON. To convert hexadecimal to decimal, you must 
use an assignment statement, prefacing the hexadecimal value you want to 
convert with the characters X' and assigning the value to a variable 
symbol. 

When 'HEX ON* is in effect, the following additional rules and 
restrictions apply to tokens on EXEC control statements: 

1. Any token, variable argument, or combination which results in a 

token with the string X* as the first two characters (this will be 

referrred to as an X» token) must also result in the next six 
characters being either: 

(a) A valid decimal number, if the token is part of an EXEC 
control which is not an assignment statement, or a valid 
hexadcimal number, if the token is part of an EXEC control 
statement which is an assignment statement. 

(b) The numbers mentioned in item 1a may be positive (no sign) , or 
negative, (prefixed with a minus sign (-220 or -FE)). The 
negative hexadecimal number is the absolute hexadecimal number 
prefixed with a minus sign (-F is a hexadecimal minus F, not a 
minus. 

(c) These numbers may be explicit (in the orginal token) , or 
substituted from a variable or an argument (for example, 
X»SX) . 

(d) The rules for token length apply with »SHEX ON*. 

(e) The range of decimal numbers that may be contained in an X' 
token is -99999 to 999999. The range of hexadecimal numbers 
that may be contained in an X* token is -FFFFF to FFFFFF. The 
above range of numbers may be extended by placing the number 
to be converted in a variable or an argument and substituting 
at conversion time. If this is done, the conversion is 
accomplished using the variable or the argument as the number 
source. The range for decimal numbers is -9999999 to 99999999, 
the range for hexadecimal numbers is SFSEOFF to -98967F. 

These examples illustrate this feature: 

SY = X'FFFFFF SY = 16777215 

STYPE X'SY STYPE FFFFFF 

SY = 5F5E0FF SY = 5F5E0FF 

SX = X'SY SX = S9999999 

(f) The notation X*-SX should not be used, because this will cause 
unwanted truncations and conversion errors. 
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If these restrictions are violated, a conversion error or 
inconsistant conversion will result. 

These statements are not valid if "HEX ON' is in effect: 

&HEX ON 

8X = X«50 CAUSES CONVERSION ERROR - See Item 1a above 

This sequence results in a conversion error because SX does not 
contain a decimal number after the X*, so the &TYPE statement 
violates item 1a above. 

8HEX ON 

&X = &LITERAL X»ABC &X = X'ABC LEGAL STATEMENT 

SY = &X XY = 2748 LEGAL STATEMENT 

&TYPE SX CAUSES CONVERSION ERROR 

2. An X» token cannot appear on an EXEC statement other than an 
assignment statement (for example, &TYPE,8ir) . 

3. If an X' token appears on an assignment statement, hexadecimal to 
decimal conversion is performed before the token is used. See 
statement El in the HEX EXEC Example. 

U. The largest hexadecimal value that will be converted to decimal is 
5F5E0FF, if the number is in a variable or an argument. If 
explicitly defined, only the leftmost six digits will be used. See 
statement E2 of HEX EXEC Example. 

5. A decimal number contained in a variable or an argument and 
referenced as such on an X» token (for example, X'SX) will not be 
truncated before it is converted to a hexadecimal number. Decimal 
numbers through 99999999 may be converted to hexadecimal if they 
are first placed in a variable or an argument. 

Note that the hexadecimal number typed is seven digits long. 

Example: 

SHEX ON 

SX = 99999999 SX = 99999999 

STYPE X'SX STYPE 5F5E0FF 

The following illustrates conversions with VSHEX ON' in effect: 

J|X1C Control Statements Result Afi§£ Substitution 

SCONTROL ALL 

-El SHEX ON 

SNUM = X'FFFFFF SNUM = 16777215 

STYPE HEX' SNUM = DEC SNUM STYPE HEX FFFFFF 

= DEC 16777215 

-E2 SIF X' 16777215 = X'SNUM SGOTO -E3 5IF 28F5C = FFFFFF 

SGOTO -E3 

STYPE SLITERAL X» 16777215 STYPE X' 167772 NE X'SNUM 

NE SLITERAL X'SNUM 

STYPE X« 16777215 NE X'SNUM STYPE 28F5C NE FFFFFF 

-E3 SNUM = X'10 SNUM = 16 

SY = SNUM + X'B SY = 16 + 11 

STYPE SY X'SY STYPE 27 IB 

-EU SY = X'NUM SY = 22 

SZ = SCONCAT SLITERAL X'1 X'SNUM SZ = SCONCAT X»1 22 

SHEX OFF SHEX OFF 

STYPE SY SZ STYPE 22 X'122 

SHEX ON SHEX ON 

STYPE SY SZ STYPE 22 7A 
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To suppress hexadecimal conversion during an EXEC procedure after 
having used it, you can use the EXEC control statement: 

SHEX OFF 

so you can use tokens containing the characters X» without the EXEC 
processor converting them to hexadecimal - 



Arguments 

An argument in an EXEC procedure is one of the special variable symbols 
61 through 830 that are assigned values when the EXEC is invoked. For 
example, if the EXEC named LINKS is invoked with the line: 

links viola ariel oberon 

the tokens VIOLA, ARIEL, and OBERON are arguments and are assigned to 
the variable symbols 81, 82, and 83, respectively. 

You can pass as many as 30 arguments to an EXEC procedure; thus the 
variable symbols you can set range from 81 to 830- These variables are 
collectively referred to as the special variable 8n. Once these symbols 
are defined, they can be used and manipulated in the same manner as any 
other variable in an EXEC. They can be tested, displayed, changed, and, 
if they contain numeric guantities, used arithmetically. 

8IF 82 EQ PRINT 8G0T0 -PR 
&TYPE 81 IS AN INVALID ARGUMENT 
81 = 2 
8CT = 81 ♦ 100 

The above examples illustrate some explicit methods of manipulating the 
8n variables. They can also be implicitly defined or redefined by two 
EXEC control statements: 8ARGS and 8READ ARGS. 

An 8ARGS control statement redefines all of the special Sn variables. 
The statement: 

8ARGS ABC 

assigns the value of A, B, and C to the variables 81, 82, and 83 and 
sets the remaining variables, 84 through 830, to blanks. 

You can also redefine arguments interactively by using the 8READ ARGS 
control statement. When EXEC processes this statement, a read request is 
presented to your terminal, and the tokens you enter are assigned to the 
8n variables. For example, the lines: 

8TYPE ENTER FILE NAME AND TYPE: 
8READ ARGS 
STATE 81 82 * 

request you to enter two tokens, and then treat these tokens as the 
arguments 81 and 82. The remaining variables 83 through 830 are set to 
blanks. 

If you want to redefine specific 8n variables, and leave the values 
of others intact, you can either redefine the individual variables in 
separate assignment statements, or use the variable symbol in the 8ARGS 
or 8READ ARGS Statement. For example, the statement: 

8ARGS CONT 82 83 RETURN 85 86 87 88 89 810 
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assigns new values to the variables SI and &H, but does not change the 
existing values for the remaining symbols through &10. 

If you need to set an argument or &n special variable to blanks, 

either on an EXEC command line or in an &ARGS or &READ ARCS control 

statement, you can use a percent sign (%) in its place. For example, the 
lines: 

&ARGS SET QUERY % TYPE 
8TYPE 81 &2 83 84 

result in the display: 

SET QUERY TYPE 

The symbol 83 has a value of blanks, and as a null token, is discarded 
from the line. 



USING THE 8INDEX SPECIAL VARIABLE 



The EXEC special variable, 8INDEX, initially contains a numeric value 
corresponding to the number of arguments defined when the EXEC was 
invoked. The value of &INDEX is reset whenever an 8ARGS or 8READ ARGS 
control statement is executed. 

SINDEX can be useful in many circumstances. If you create an EXEC 
that may expect any number of arguments, and you are going to perform 
the same operation for each, you might set a counter and use the value 
of 8INDEX to test it. For example, an EXEC named PRISTX accepts 
arguments that are the filenames of ASSEMBLE files: 

&CT = 1 

SLOOP 2 SCT > SINDEX 
PRINT SSCT ASSEMBLE 
SCT = SCT + 1 

In the preceding example, the token SCT is substituted with 81, 82, and 
so on until all of the arguments entered on the PRINTX line are used. 

You can also use SINDEX to test the number of arguments entered. If 
you design an EXEC to expect at least two arguments, the procedure might 
contain the statements: 

SIF SINDEX LT 2 SGOTO -ERRi 



-ERR1 STYPE INVALID COMMAND LINE 
SEXIT 1 

In this example, if the EXEC is invoked with one or no arguments, an 
error message is displayed and the EXEC terminates processing with a 
return code of 1. 

As another example, suppose you wanted to supply an EXEC with default 
arguments, which might or might not be overridden. If the EXEC is 
invoked with no arguments, the default values are in effect; if it is 
invoked with arguments, the arguments replace the default values: 
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&DISP = PRINT 

8CO0NT =2 

8IF SINDEX GT 2 SEXIT 1 

SIF SINDEX EQ SGOTO -GO 

SCODNT = SI 

SIF SINDEX = 2 8DISP = 62 

-GO 

Default values are supplied for the variables SEISP and SCODNT. Then, 
SINDEX is tested, and the variables are reset if any arguments were 
entered. 



CHECKING ARGUMENTS 



There are a number of tests that you can perform on arguments passed to 
an EXEC. In some cases, you may want to test for the length of a 
specific argument or to test whether an argument is character data or 
numeric data. To perform these tests, you can use the EXEC built-in 
functions SLENGTH and SDATATYPE. 

To use either SLENGTH or SDATATYPE, you must first assign a variable 
to receive the result of the function, and then test the variable- For 
example, to test whether an entered argument is five characters long, 
you could use the statements: 

SLIMIT = SLENGTH Si 

SIF SLIMIT GT 5 SEXIT SLIMIT 

Hhen these statements are executed, if the first argument (SI) is 
greater than five characters, the exit is taken, and the return code 
indicates the length of SI. 



If you wish to check whether a 
use the SDATATYPE function: 



number was entered for an argument. 



SSTRING = SDATATYPE S2 

SIF SSTRING -1= NUM SGOTO -ERR4 

In this example, the second argument expected by the EXEC must be a 
numeric quantity. If it is not, a branch is taken to an error exit 
routine. 

Often, you may create an EXEC that tests for specific arguments and 
then takes various paths, depending on the argument. For example: 



SIF S2 
SIF S2 
SIF S2 

SEXIT 



PRINT SGOTO -PR 
TYPE SGOTO -TY 
ERASE SGOTO -ER 



In this EXEC, if the value of S2 is not PRINT, TYPE, or 
not entered, the EXEC terminates processing. 



ERASE, or was 



S* and S$ 



There are two special EXEC keywords that you may use to test arguments 
passed in an EXEC. They are S* and S$, which can be used only in an SIF 
or an SLOOP control statement. They test the entire range of numeric 
variables S1 through S30, as follows: 



( 
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8$: The special token &$ is interpreted as "any of the variables 81, 82, 
..., 830." That is, if the value of any one of the numeric variables 
satisfies the established condition, then the 8IF statement is 
considered to be true. The statement is false only «hen none of the 
variables fulfills the specified requirements. 

As an example, suppose you want to make sure that some particular 
value is passed to the EXEC. You can check to see if any of the 
arguments satisfy this condition, as follows: 

&IF 8$ EQ PRINT 8SKIP 2 

8TYPE PARM LIST MUST INCLUDE PRINT 

8EXIT 

In this example, the path to the 8TYPE statement is taken only when none 
of the arguments passed to the EXEC procedure equal the character string 
PRINT. 

8*: The special token 8* is interpreted as "all of the variables 81, 82, 
..., 830." That is, if the value of each of the numeric variables 
satisfies the established condition, then the 8IF statement is 
considered to be true. The statement is false when at least one of the 
variables fails to meet the specified requirements. 

Use 8* to test for the absence of an argument as follows: 

8IF 8* NE ASSEMBLE 8EXIT 3 

In this example, if an EXEC is invoked, and none of the arguments equals 
ASSEMBLE, the EXEC terminates with a return code of 3. 

The tokens 8* and 8$ are set by arguments entered when an EXEC is 
invoked and reset when you issue an 8ARGS or 8READ ARGS control 
statement. If either 8* or 8$ is null because no arguments are entered, 
the 8IF statement is considered a null statement, and no error occurs. 

Execution Paths in an EXEC 

You have already seen examples of the 8IF, 8G0T0, 8SKIP, and 8L0CP 
control statements. A more detailed discussion on each of these 
statements and additional techniques for controlling execution paths in 
an EXEC procedure follow. 

LABELS IN AN EXEC PROCEDURE 

In many instances, an execution control statement in an EXEC procedure 
causes a branch to a particular statement that is identified by a label. 
The rules and conventions for creating syntactically correct EXEC labels 
are: 

• A label must begin with a hyphen (dash) and must have at least one 
additional character following the hyphen. 

• Up to seven additional alphameric characters may follow the hyphen 
(with no intervening blanks). However, the sequence: 

8G0T0 -PROBABLY 



-PROBABLY 
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executes saccessfully, because when each statement is scanned, the 
token -PROBABLY is truncated to the same eight-character token, 
-PROBABL. 

A label name may be the object of an SGOTO or SLOOP control 
statement. 

A label that is branched to must be the first token on a line. It 
may stand by itself, with no other tokens on the line, or it may 
precede an executable CMS command or EXEC control statement. 

The following are examples of the correct use of labels: 

SGOTO -LABI 

-LABI 

-LAB2 6CONTIH0E 

-CHECK SIF 6INDEX EQ SGOTO -EXIT 

SIF SINDEX LT 5 SSKIP 

-EXIT SEXIT 4 

STYPE SLITERAL SINDEX VALUE IS SINDEX 



CONDITIONAL EXECUTION WITH THE SIF STATEMENT 

The main tool available to you for controlling conditional execution in 
an EXEC procedure is the SIF control statement. The SIF control 
statement provides the decision-making ability that you need to set up 
conditional branches in your EXEC procedure. 

One approach to decision-making with the SIF control statement is to 
compare two tokens, and perform some action based on the result of the 
comparison. Hhen the comparison specified is equal (or true), the 
executable statement is executed. When the comparison is unequal (or 
false) , control passes to the next sequential statement in the EXEC 
procedure. An example of a simple SIF statement is: 

SIF SI EQ S2 STYPE MATCH FOUND 

If the comparand values are not equal, the statement STYPE MATCH 
FOUND is not executed, and control passes to the next statement in the 
EXEC procedure. If the comparand values are equal, the statement STYPE 
MATCH FOUND is executed before control passes to the next statement. 
SIF statements can also be used to establish a comparison between a 
variable and a constant. For example, if a terminal user could properly 
enter a YES or NO response to a prompting message, you could set up SIF 
statements to check the response as follows: 

SREAD ARGS 

SIF SI EQ YES SGOTO -YESANS 

SIF SI EQ NO SGOTO -NOANS 

STYPE SI IS NOT A VALID RESPONSE (MUST BE YES OR NO) 

SEXIT 

-YESANS 



-NOANS 



In this example, the branch to -YESANS is taken if the entered 
argument is YES; otherwise, control passes to the next SIF statement. 
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The branch to -NOANS is taken if the argument is HO; otherwise, control 
passes to the &TYPE statement, which displays the entered argument in an 
error message and exits. 

The test performed in an SIF statement need not be a simple test of 

equality between two tokens; other types of comparisons can be tested, 

and more than two variables can be involved. The tests that can be 
performed and the symbols you can use to represent them are: 

Symbol Mnemonic Meaning 

= EQ" a equals B 

-'= NE A does not equal B 

< LT A is less than B 

<= LE A is less than or equal to B (not greater than) 

> GT A is greater than B 

>= GE A is greater than or equal to B (not less than) 



Compound &IF Statements 

You can place multiple SIF control statements on one line, to test a 
variable for more than one condition. For example, the statement: 

&IF SNOM GT 5 SIF SNDM LT 10 STYPE O.K. 

checks the variable symbol SNOM for a value greater than 5 and less than 
10. If both of these conditions are satisfied, the SIF statement is 
true, and the STYPE statement is executed. If either condition is false, 
then the STYPE statement is not executed. 

The number of SIF statements that may be nested is limited only by 
restrictions placed on the record length of the EXEC file. 



BRANCHING WITH THE SGOTO STATEMENT 

The SGOTO control statement allows you to transfer control within your 
EXEC procedure: 

• To a specified EXEC label somewhere in the EXEC file: 

SGOTO -TEST 
where -TEST is the label to which control is passed. 

• To a particular line within the EXEC file. For example: 

SGOTO 15 
results in control being passed to statement 15 in the EXEC file. 

• Directly to the top of the EXEC file. For example: 

SGOTO TOP 
passes control to the beginning of the EXEC procedure. 
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The &GOTO control statement can be coded wherever an executable 
statement is permitted in an EXEC procedure. One of its common uses is 
in conjunction with the SIF control statement. For example, in the 
statement: 

SIF SINDEX EQ SGOTO -ERROR 

the branch to the statement labeled -ERROR is taken when the value of 
the &INDEX special variable is zero. Otherwise, control passes to the 
next sequential statement in the EXEC procedure. 

An &GOTO statement can also stand alone as an EXEC control statement. 
When coded as such, it forces an unconditional branch to the specified 
location. For example, you might create an EXEC that has several 
execution paths, each of which terminates with an SGOTO statement 
leading to a common exit routine: 

-PATH1 SCONTINOE 



SGOTO -EXIT 
-PATH2 8C0NTINUE 



SGOTO -EXIT 
SPATH3 SCONTINUE 



-EXIT SCONTINUE 

A 

You can use the SGOTO control statement to establish a loop. For L 
example: 

SGL0BAL1 = SGL0BAL1 +1 

STYPE ENTER NUMBER: 

SREAD VARS SNEXT 

SIF .SNEXT = . SGOTO -FINIS 

SIF SGL0BAL1 = 2 STOTAL = 

STOTAL = STOTAL «■ SNEXT 

SGOTO TOP 

-FINIS 

STYPE TOTAL IS STOTAL 

In this EXEC example, all of the statements, through the SGOTO TOP 

statement, are executed repeatedly until a null line is entered in 

response to the prompting message. Then, the branch is taken to the 
label -FINIS and the total is typed. 

Note the use of the special variable SGL0EAL1 in the preceding 
example. The SGLOBALn special variables are self- initializing and have 
an initial value of 1. 



Dsinjg the SGOTO Control Statement 

When an EXEC procedure processes an SGOTO statement, and searches for a 
given label or line number, the scan begins on the line following the 
SGOTO statement, proceeds to the bottom of the file, then wraps around 
to the top of the file and continues to the line immediately preceding 
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the SGOTO stateaent. If there are duplicate labels in an EXEC file, the 
first label encountered during the search is the one that is branched 
to. 

If the label or line number is not found during the scan, EXEC 
terminates processing and displays the message: 

ERROR IN EXEC FILE filename, LINE n - SSKIP or SGOTO ERROR 

If the label or line number is found, control is passed to that location 
and execution continues. 



BRANCHING WITH THE &SKIP STATEMENT 

The SSKIP control statement provides you with a second method of passing 
control to various points in an EXEC procedure. Instead of branching to 
a named or numbered location in an EXEC procedure, SSKIP passes control 
a specified number of lines forward or backward in the file. 

You pass control forward in an EXEC by specifying how many lines to 
skip. For example, to handle a conditional exit from an EXEC procedure, 
you could code the following: 

6IF SRETCODE EQ SSKIP 
SEXIT SRETCODE 

where the SEXIT statement is skipped whenever the value of SRETCODE 
equals zero. If the value of SRETCODE does not equal zero, control 
passes out of the current EXEC procedure with a return code that is the 
nonzero value in SRETCODE. Note that when no SSKIP operand is 
specified, a value of 1 is assumed. 

A succession of SSKIP statements can be used to perform multiple 
tests on a variable. For example, suppose an argument should contain a 
value from 5 to 10 inclusive: 

SIF SI LT 5 SSKIP 

SIF S1 LE 10 SSKIP 

STYPE SI IS NOT WITHIN RANGE 5-10 

If the value of SI is less than 5, control passes to the STYPE control 
statement, which displays the erroneous value and an explanatory 
message. If the value of Si is greater than or equal to 5, the next 
statement checks to see if it is less than or equal to 10. If this is 
true, then the value is between 5 and 10 inclusive, and execution 
continues following the STYPE statement. 

When you want to pass control to a statement that precedes the 
current line, determine how many lines backward you want to go, and code 
SSKIP with the desired negative value: 

SVAL = 1 

STYPE SYAL 

6VAL = S7AL ♦ 1 

SIF SVAL NE 10 SSKIP -2 

In this EXEC, the STYPE statement is executed repeatedly until the value 
of STAL is 10, and then execution continues with the statement following 
the SIF statement. 
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USING COUNTERS FOR LOOP CONTROL 



A primary consideration in designing a portion of an EXEC procedure that 
is to be executed many times is how to control the number of executions. 
One way to dontrol the execution of a sequence of instructions is to 
create a loop that tests and changes the value of a counter. 

Before entering the loop, the counter is initiali2ed to a value. 
Each time through the loop, the counter is adjusted (increased or 
decreased) toward a limit value. When the limit value is reached (the 
counter value is the same as the limit value) , control passes out of the 
loop and it is not executed again. For example, the following EXEC 
initializes a counter based on the argument S1: 

SIF SINDEX EQ SEXIT 12 

6TYPE COUNT IS S1 

SI = SI - 1 

SIF SI GT SSKIP -2 

When this EXEC procedure is invoked, it checks that at least one 
argument was passed to it. If an argument is passed, it is assumed to 
be a number that indicates how many times the loop is to execute. Each 
time it passes through the loop, the value of SI is decreased by 1. 
When the value of &1 reaches zero, control passes from the loop to the 
next sequential statement. 

There are several ways of setting, adjusting, and testing counters. 
Some ways to set counters are by: 

• Reading arguments from a terminal, such as: 

SREAD VARS SC0UNT1 SC0UNT2 

• Assigning an arbitrary value, such as: 

SCOUNTER = 43 

• Assigning a variable value or expression, such as: 

SCOUNTS = SINDEX - 1 

Counter values can be increased or decreased by any increment or 
decrement that meets your purposes. For example: 

SCOUNTEM = SCOUHTEM - SRETCODE 
SC0UNT1 = SCOUNT + 100 



LOOP CONTROL WITH THE SLOOP STATEMENT 



A convenient way to control execution of a sequence of EXEC statements 
is with the SLOOP control statement. An SLOOP statement can be set up 
in four ways: 

• To execute a particular number of statements a specified number of 
times. For example, the statement: 

SLOOP 3 2 

indicates that the three statements following the SLOOP statement are 
to be executed twice. 



( 
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• To execute a particular nuaber of statements until a specified 
condition is satisfied. For example: 

&LOOP U SX = 

The four statements following this statement are executed until the 
value of &X is 0. 

• To execute the statements down to (and including) the statement 
identified by a label for a specified number of times. For example: 

SLOOP -ENDLOOP 6 

The statements between this SLOOP statement and the label -EMDLOCP 
are executed six times. 

• To execute the statements down to (and including) the statement 
identified by a label until a specified condition is satisfied. In 
the following example: 

SLOOP -ENDLOOP SX = 

the statements are executed repeatedly until the value of SX is 0. 

The numbers specified for the number of lines to execute and the 
number of times through the loop must be positive integers. Tou can use 
a variable symbol to represent the integer. If a label is used to 
define the limit of the loop, it must follow the SLOOP statement (it 
cannot precede the SLOOP statement) . 

In a conditional SLOOP statement, any variable symbols in the 
conditional phrase are substituted each time the loop is executed. For 
example, the statements: 

SX = 

SLOOP -END SX EQ 2 

SX = SX ♦ 1 

-END STYPE SX 

are interpreted and executed as follows: 

1. The variable SX is assigned a value of 0. 

2. The SLOOP statement is interpreted as a conditional form; that is, 
to loop to -END until the value of SX equals 2. Since the value of 
SX is not 2, the loop is entered. 

3. The variable SX is increased by 1 and is then displayed. 

4- Control returns to the beginning of the loop, where SX is tested to 
see if it equals 2. Since it does not, the loop is executed again 
and 2 is displayed. The next time through the loop, when SX equals 
2, control is passed to the EXEC statement immediately following 
the label -END. 

When this EXEC procedure is executed, the following lines are 
displayed: 

1 

2 

at which time the value of SX equals 2; the loop is not executed again. 
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Another exafflple of a conditional loop is: 

8Y = 8LITERA1 ASB 
SLOOP 2 .SX EQ 6LITERAL .S 
SX = SSOBSTB SY 2 1 
8TYPE &X 

These stateaents are interpreted and executed as follows: 

1. The variable 6Y is set to the literal value ASB. 

2. The two stateaents following the SLOOP statement are to be executed 
until the value of SX is S. 

3. The SSOBSTR built-in function is used to set the variable SX to the 
value of the second character in the variable SY, which is a 
literal ampersand (S) . 

H, The ampersand is typed once, and the loop does not execute again 
because the condition that the value of SX be a literal ampersand 
is met. 



NESTING EXEC PROCEDURES 

If you want to use an EXEC procedure within another EXEC, you must use 
the EXEC command to execute it. For example, if you have the statement: 

EXEC TEST 

in an EXEC procedure, it invokes the EXEC procedure TEST. The procedure 
TEST EXEC executes independently of the other EXEC; the variables SI, S2 
and so on are assigned values and the default settings for control 
statements such as SCONTROL and SHEX are reset. When TEST EXEC 
completes execution, control returns to the next line in the calling 
EXEC, where the values for variable symbols and EXEC settings are the 
same as when the TEST EXEC was invoked. 



Pa ssi ng Arguments to Nested Procedures 

Variables in an EXEC file have meaning only within the particular 
procedure in which they are defined. There are two methods you can use 
to pass variable information to nested EXECs. One way is to pass 
arguments on the EXEC command line. For example, if the CHECK EXEC 
contains the line: 

EXEC COONTEM SITEMCT SNUM 

then the current values of SITEHCT and SNUH are assigned to the variable 
symbols SI and S2 in COUNTEM EXEC. (The values of 81 and S2 in CHECK 
EXEC do not change.) 

You can also use the ten special variables SGLOBALO through SGL0BAL9. 
These variables can only contain integral numeric values; you cannot 
assign them character-string values. These variables can be used to set 
up arguments to pass to nested procedures, or to communicate between 
EXEC files at different recursion levels. 
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Thus, if CHECK EXEC contains: 

&GL0BAL1 = 100 
EXEC COONTEM 

The variable &GL0BAL1 has a value of 100 in CODNTEM EXEC, which may also 
test and modify it. 

The EXEC interpreter can handle up to 19 levels of recursion at one 
time, that is, up to 19 EXECs may be active, one nested within another. 
An EXEC may also call itself. 

You can test the &GLOBAL special variable to see if an EXEC is 
executing within another procedure and if so, at what level of recursion 
it is executing. For example, if the file RECOUP EXEC contained the 
lines: 

&IF SGLOBAL EQ 2 &GOTO -2NDPASS 



EXEC RECOMP 



-2NDPASS STYPE SECOND PASS BEGINS 

then when the line "EXEC RECOMP" is executed, control passes to the 
beginning of the EXEC; the value of &GLOBAL changes from 1 to 2; and 
control is passed to the STYPE statement at the label 2NDPASS. 



EXITING FROM EXEC PROCEDURES 

Execution in an EXEC procedure proceeds sequentially through a file, 
line by line. When a statement causes control to be passed to another 
statement, execution continues at the second statement, and again 
proceeds sequentially through the file. When the end of the file is 
reached, the EXEC terminates processing. Frequently, however, you may 
not want processing to continue to the end of the file. You can use the 
&EXIT statement to cause an immediate exit from EXEC processing and a 
return to the CMS environment. If the EXEC has been invoked from 
another EXEC, control is returned to the calling EXEC file. For 
example, the statement: 

&IF SRETCODE -•= 8EXIT 

would cause an immediate exit from the EXEC if the return code from the 
last issued CMS command was not zero. 

You can use the &EXIT statement to terminate each of a series of 
execution paths in an EXEC. For example, using the following 
statements. 
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SIF 61 EQ PRINT SGOTO -PRINT 
SIF SI EQ TYPE SGOTO -TYPE 



-PRINT 



SEXIT 
-TYPE 



SEXIT 



you ensure that once the path through the -PRINT routine has been taken, 
the EXEC does not continue processing with the -TYPE routine. 



Ij^llil Return Codes Fron EXECs 

The SEXIT control statement also provides a special function that allows 
you to pass a return code to CMS or to the program or EXEC that called 
this EXEC. You specify the return code value on the SEXIT control 
statement as follows: 

SEXIT 4 

Execution of this line results in a return to CMS with a ready message: 

R (00004) ; 

If you have a variety of exits in an EXEC, you can use a different value 
following each SEXIT statement, to indicate which path had been taken in 

the EXEC. 

You can also use a variable symbol as the value to be passed as the 
return code: 

SEXIT SVAL 

Another common use of the SEXIT statement is to cause an exit to be 
taken following an error in a CHS command, and using the return code 
from the CMS command in the SEXIT statement: 

SIF SRETCODE NE SEXIT SRETCODE 



Terminal Communications 



You can design EXECs to be used interactively, so that their execution 
depends on information entered directly from the terminal during the 
execution. With the STYPE statement, you can display a line at the 
terminal, and with the SREAD statement, you can read one or more lines 
from the terminal or console stack. Used together, these statements can 
provide a prompting function in an EXEC: 



i 
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&TYPE WHAT DO 100 HANT TO DO NOW? 
STYPE ENTER (STOP CONTINUE REPEAT) 
&READ VARS &LABEL 
SGOTO -&LABEL 
-STOP 



-CONTINUE 



-REPEAT 



In this example, the 6READ control statement is used with the VARS 
operand, which accepts the words entered at the terminal as values to be 
assigned to variable symbols. If the word STOP is entered in response to 
the &READ VARS statement in this example, the variable symbol &LABEL is 
assigned the value STOP. Then, in the &GOTO statement, the symbol is 
substituted with the value STOP, so the branch is taken to the label 
-STOP. 

You can specify up to 17 variable names on an 8READ VARS control 
statement. If you enter fewer words than are expected, the remaining 
variables are set to blanks. If you enter a null line, any variable 
symbols on the &READ line are set to blanks. If the execution of your 
EXEC depends on a value entered as a result of an SREAD VARS, you might 
want to include a test for a null line immediately following the 
statement; for example: 

SREAD VARS 8TITLE SSUBJ 
6IF .&TITLE = . 8EXIT 100 

If no tokens are entered in response to the terminal read request, the 
variable &TITLE is null, and the EXEC terminates with a return code of 
100. 

If you are writing an EXEC that may receive a number of tokens from 
the terminal, you may find it more convenient to use the SREAD ARGS form 
of the SREAD control statement. When the SREAD ARGS statement reads a 
line from the terminal, the tokens entered are assigned to the Sn 
special variables (SI, S2, and so on) . 

READING CMS COMMANDS AND EXEC CONTROL STATEMENTS FROM THE TERMINAL 

When you use the SREAD control statement with no operands, or with a 
numeric value, EXEC reads one line or the specified number of lines from 
the terminal. These lines are treated, by EXEC, as if they were in the 
EXEC file all along. For example, if you have an EXEC named COMMAND that 
looks like the following: 

STYPE ENTER NEXT COMMAND: 
SREAD 1 
SSKIP -2 



) 



all the commands you enter during the terminal session are processed by 
the EXEC. Each time the SREAD statement is executed, you enter a CHS 
command. When the command finishes, control returns to EXEC, which 
prompts you to enter the next command. Since the CHS commands are all 
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being executed from within the EXEC, you do not receive the CMS ready 
message at the completion of each command. 

You could also enter EXEC control statements or assignment 
statements. To terminate the EXEC and return to the CMS environment, 
you must enter the EXEC control statement SEXIT from the terminal: 

8exit 



DISPLAYING DATA AT A TERMINAL 

You can use the STYPE and SBEGTYPE control statements to display lines 
from your EXEC at the terminal. In addition, you can use the CMS TYPE 
command to display the contents of CMS files. 

When you use the STYPE control statement, you can display variable 
symbols as well as data. Variable symbols on an STYPE control statement 
are substituted before they are displayed. For example, the lines: 

SNAME = ARCHER 
STYPE SNAME 

result in the display: 

ARCHER 

You can use the STYPE statement to display prompting messages, error 
or information messages, or lines of data. 

In an EXEC file with fixed-length records, only the first 72 
characters of each line are processed by the EXEC interpreter. 
Therefore, if you want to use the STYPE control statement to display a 
line longer than 72 characters, you must convert the file into 
variable-length records. 



SBEGTYPE and 6BEGTY£1 ALL 

All of the words in an STYPE control statement are scanned into 
8-character tokens. If you need to display a word that has more than 8 
characters, you must use the SBEGTYPE control statement. The SBEGTYPE 
control statement precedes one or more data lines that you want to 
display; for example: 

SBEGTYPE 

THIS EXEC PERFORMS THE FOLLOWING FUNCTIONS: 

1. IT ACCESSES DISKS 193, 19U, and 195 AS 
B, C, AND D EXTENSIONS OF THE A-DISK. 

2. IT DEFINES, FORMATS, AND ACCESSES A 
TEMPORARY 195 DISK (E) . 

SEND 

The SEND statement must be used to terminate a series of lines 
introduced with the SBEGTYPE statement- "SEND" must begin in column 1 of 
the EXEC file. 

The lines following an SBEGTYPE statement, up to the SEND statement, 
are not scanned by the EXEC interpreter. Therefore, no substitution is 
performed on the variable symbols on these data lines. If you need to 
display a symbol, you must use the STYPE control statement. To display a 
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combination of scanned and unscanned lines, you might need to use both 
the STYPE and SBEGTYPE control statements: 

&BEGTYPE 

EVALUATION BEGINS... 

SEND 

STYPE 6VAL1 IS SNUM1. 

STYPE SVAL2 IS 6N0M2. 

SBEGTYPE 

EVALUATION COMPLETE. 

SEND 

If you use the SBEGTYPE control statement in an EXEC file with 
fixed-length records, and you want to display lines longer than 72 
characters, you must use the ALL operand. For example: 

SBEGTYPE ALL 

...data line of 103 characters 

...data line of 98 characters 

...data line of 50 characters 

SEND 

You can display lines of up to 130 characters in this way. When you 
enter lines that are longer than the record length in an EXEC file, the 
records are truncated by the editor. You must increase the record length 
of the file by using the LRECL option of the EDIT command, for example: 

edit old exec a (Irecl 130 

In a variable-length EXEC file, you do not need to specify ALL to 
display long lines. If you originally created the file with a record 
length of 130 characters, you do not need to increase the size later to 
accomodate longer records. 



Using the CMS TYPE Command 

You can use the TYPE command in an EXEC file to display data files, or 
portions of data files. For example, you might have a number of files 
with the same filetype; the files contain various kinds of data. You 
could create an EXEC that invokes the TYPE command to display a 
particular file as follows: 

SIF SINDEX EQ 2 SIF S2 EQ ? SGOTO -TYPE 



-TYPE 

ACCESS 198 B 
TYPE SI MEMO B 

The filetype MEMO is a reserved filetype, which accepts data in 
uppercase and lowercase; you can use it for documentation files or 
programming notes. 



Controlling Terminal Dis£la2s 

The two CMS Immediate commands that control terminal display are HT 
(halt typing) and ST (resume typing) . When data is being displayed at 
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your terminal, you can suppress the display by signaling an attention 
interruption and entering: 

ht 

This command affects output that is being displayed: 

• As a response to a CMS command, including prompting messages, error 
messages, or normal display responses (as from the TYPE command) 

• From a program 

• In response to an STYPE or 8BEGTYPE request in an EXEC 

Once display has been suppressed, and before the command, program, or 
EXEC completes execution, you can request that display be resumed by 
signaling another interruption and entering: 

rt 

In an EXEC file, if you want to halt or resume display, you must use 
the SSTACK control statement to enter the RT or HT commands. For 
example, the ACCESS command issues a message when a disk is accessed: 

D(198) R/0 

If you are going to issue the ACCESS command within an EXEC and you do 
not wish this message displayed, you could enter the lines: 

8STACK HT 
ACCESS 198 D 

Once you have stacked an HT command, all displaying is suppressed for 
the remainder of the EXEC file's execution, unless the RT Immediate 
command is processed, either following an attention interruption (as 
described above) or within the EXEC. To execute the RT Immediate 
command in an EXEC, use the statement: 

SSTACK RT 

A physical read to the terminal, for example the result of an SREAD 
control statement, also resets the display setting to RT. 

The &TYPEFLAG Special Variable: You can test the current value of the 
display controlling^ an EXEC with the 8TYPEFLAG special variable. The 
value of STYPEFLAG can only be one of the literal values HT or RT. For 
example: 

&IF &$ EQ NOTYPE SSTACK HT 



SIF STYPEFLAG EQ HT SSKIP 3 

STYPE LINE1 

STYPE LINE2 

STYPE LINE3 

SCONTINUE 

In this example, if NOTYPE is entered as an argument when the EXEC is 
invoked, an HT command is stacked, so that no displaying is done at the 
terminal. Within the EXEC, the variable STYPEFLAG is tested, and, if it 
is HT, then a series of STYPE statements is skipped. Since EXEC does 
not have to process these lines, you can save time and system resources 
by not processing them. 



( 



288 IBM VM/370 CMS User's Guide 



) 



w 



Reading from the Console Stack 

when you are in the CMS environment executing programs or CMS commands, 
you can stack commands, either by entering multiple command lines 
separated by the logical line end symbol, as follows: 

print myfile listing#cp query printer 

or by signaling an attention interruption and entering a command line, 
as follows: 

print myfile listing 
t 

cp query printer 

In both of the preceding examples, the second command line is saved 
in a terminal input buffer, called the console stack. Whenever a read 
occurs in your virtual machine, CMS reads lines from the console stack, 
if there are any lines in it. If there are no lines in the stack, the 
read results in a physical read to your terminal (on a typewriter 
terminal, the keyboard unlocks) . 

A virtual machine read occurs whenever a command or subcommand 
finishes execution, or when an EXEC or a program issues a read request. 
Many CMS commands also issue read requests, for example, SORT and 
COPYFILE. If you want to execute one of these commands in an EXEC, you 
may want to stack, in the console stack, the response to the read 
request so that when it is issued it is immediately satisfied. For 
example: 

SSTACK 42-121 1 

COPYFILE &NAME LISTING A = ASSEMBLE = (SPECS 

When the COPYFILE command is issued with the SPECS option, a prompting 
message for a specification list is issued, followed by a read request. 
In this EXEC, the request is satisfied with the line stacked with the 
SSTACK control statement. If the response was not stacked, you would 
have to enter the appropriate information from the terminal during the 
execution of the EXEC that contained this COPYFILE command line. 

In addition to stacking predefined responses to commands and 
programs, you can use the console stack to stack CMS commands and EDIT 
subcommands, as well as data lines to be read within the EXEC. 

The number of lines that you can place in the console stack at any 
one time varies according to the amount of storage available in your 
virtual machine for stacking. You may want to stack one or two lines at 
a time, or you may wish to stack many lines- There are several features 
available in EXEC that can help you manipulate the stack. 



SBEGSTACK and SBEGSTACK ALL 

Just as the STYPE control statement has an 8BEGTYPE counterpart, the 
&STACK control statement has an SBEGSTACK counterpart. You can stack 
multiple data lines following an SBEGSTACK statement. Lines stacked in 
this way are not scanned by the EXEC processor, and no substitution is 
performed on variable symbols. For example, the lines: 
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SBEGSTACK 
...line of data 
...line of data 
...line of data 
&END 

stack three data lines in the stack. The stacked lines must be followed 
by an SEND control statement, which must be entered in the EXEC file 
beginning in column 1. 

If you have an EXEC with fixed-length records, and you want to stack 
data lines longer than 72 characters, you must use the ALL operand of 
the SBEGSTACK control statement: 

SBEGSTACK ALL 

...line of 103 characters 

...line of 98 characters 

...line of 60 characters 

SEND 

The ALL operand is not necessary for variable-length EXEC files. 



Stackinc[ FIFO and LIFO 

When you are stacking multiple lines in an EXEC, you may choose to 
reverse the sequence in which lines are read in from the stack. The 
default sequence is FIFO (f irst-in, first-out) , but you may specify LIFO 
(last-in, first-out) when you enter the SSTACK or SBEGSTACK control 
statement. For example, execution of the lines: 

SSTACK STYPE A ^ 

SSTACK STYPE B '4 

SSTACK LIFO STYPE C 
SSTACK LIFO STYPE D 
SSTACK STYPE E 

results in the display: 

D 
C 
A 
B 
E 



The SBEApFLAG Special Variable 

The EXEC special variable SREADFLAG always contains one of two values, 
STACK or CONSOLE. Hhen it contains the value STACK, it indicates that 
there are lines in the stack. When it contains the value CONSOLE, it 
indicates that the stack is empty and that the next read request results 
in a physical read to the terminal (console) . 

You can test this value in an EXEC, for example: 

SIF SREADFLAG EQ STACK 8SKIP 2 

STYPE STACK EMPTY 

SEXIT 

SCONTINUE 



( 
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YOU night use a similar test in an EXEC that processes a nuiber of lines 
froB the stack, and loops through a series of steps until the stack is 
eipty. 

STACKING CHS COHHANDS 

Whenever you place a command in the console stack, it remains there 
until a read request is presented to the terminal. If the request is the 
result of an &READ control statement, then the line is read from the 
stack. For example, the lines: 

GSTACK CP QUERY TIME 
&READ 

result in the command line being stacked, read in, and then executed. 

If there are no read requests in an EXEC file, then any commands that 
are stacked are executed after the EXEC' has finished and has returned 
control to the CMS environment. For example, consider the lines: 

TYPE 61 LISTING A 
ACCESS 198 A 
TYPE &1 LISTING A 

If this EXEC is located on your 191 A-disk, then when the ACCESS command 
accesses a new A-disk, CMS cannot continue reading the EXEC file and 
issues an error message. However, if the EXEC was written as follows: 

TYPE SI LISTING A 
&STACK ACCESS 198 A 
6STACK TYPE SI LISTING A 

then, after the TYPE command, the next command lines are stacked, the 
EXEC finishes executing and returns control to CMS, which reads the next 
command lines from the console stack. 

When you stack CMS commands with the 6STACK control statement in an 
EXEC procedure, you cannot place multiple command lines in one statement 
separated by the logical line end symbol (for example, print abc 
listing#print xyz listing) . CP does not translate the logical line end 
symbol (#) to a value of x*15' because a line is being read from the 
EXEC file en disk and not from the terminal. However, you can place 
multiple command lines in one statement if separated by the value x*15'. 
The ALTER subcommand of EDIT can be used to insert the xM5» value. CBS 
does recognize the xM5» character. 

Stacking EDIT Subcommands 

If you want to issue the EDIT command from within an EXEC, you might 
want to stack EDIT subcommands to be read by the CMS editor. You should 
stack these subcommands, either with SSTACK statements, or with the 
8EEGSTACK statement, just before issuing the EDIT command. For example: 

SBEGSTACK 

CASE M 

GET SETUP FILE A 1 20 

TOP 

LOCATE /XX/ 

SEND 

SSTACK REPLACE 

EDIT SI DATA (LRECL 120 
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If this EXEC is named EDEX, and you invoke it with: 

edex fr01 

the EDIT subcomaands are stacked in the order they appear in the EXEC. 
The EDIT coinmand is invoked to edit the file FR01 DATA, and the EDIT 
subcommands are read from the stack and executed. When the stack is 
empty, your virtual machine is in the edit environment in input mode, 
and the first line you enter replaces the existing line that contains 
the character string XX. 

Note that all of the EDIT subcommands in the example, except for the 
REPLACE subcommand, are stacked within an &BEGSTACK stack, and that the 
REPLACE subcommand is stacked with SSTACK. If you are creating EXEC 
files with fixed- length records, you must use SSTACK to stack the INPDT 
and REPLACE subcommands. If you use SBEGSTACK, then the INPUT and 
REPLACE subcommands are treated as if they contain text data, and so 
insert or replace one line in the file (a line of blanks) . This is not 
true, however, for variable-length EXEC files. 

Similarly, if you want to stack a null line, to change from input 

mode to edit mode in an EXEC, you must use the 8STACK statement with no 

other data on the line (in both fixed- and variable-length EXEC files) , 
for example: 

SSTACK INPUT 
SBEGSTACK 
...data line 
...data line 
...data line 
&END 
SSTACK 
SSTACK FILE 
EDIT SI S2 
SEXIT 

When this EXEC is invoked with a filename and filetype as arguments, the 
INPUT subcommand, data lines, null line, and FILE subcommand are placed 
in the stack before the EDIT command is issued. The data lines are 
placed in the specified file and the file is written onto disk before 
the EXEC returns control to CMS. 



STACKING LINES FOR EXEC TO READ 

Lines in the console stack can be read by the EXEC interpreter with an 
SREAD control statement; for example: 

-SETUP 

SLOOP 3 SNUM = 50 

SSTACK SNUM SCHAR 

SNUM = SNUM +1 

SCHAR = SCONCAT SSTRNG SNUM 



-READ 

SLOOP -FINIS SREADFLAG EQ CONSOLE 
SREAD ARGS 



-FINIS 



i 
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In this EXEC procedure, the statements following the label -SETUP stack 
a number of lines. The variables &NOM and &CHAR are substituted before 
they are stacked. J,t the label -READ, the lines are read in from the 
stack and processed. The values stacked are read in as the variable 
symbols &1 and S2. Control passes out of the loop when the stack is 
empty. 



CLEARING THE CONSOLE STACK 

If you use the console stack in an EXEC procedure, you should be sure 
that it is empty before you begin stacking lines in it. Also, you 
should be sure that it is empty before exiting from the EXEC (unless you 
have purposely stacked CMS commands for execution) . 

One way to clear a line from the stack without affecting the 
execution of your EXEC is to use the 6READ VARS or 8READ ARGS control 
statement. You can use 5READ VARS without specifying any variable 
symbols so that the line read is read in and effectively ignored. For 
example: 

SLOOP 1 SREADFLAG EQ STACK 
&READ ARGS 

If these lines occur at the beginning of an EXEC file, they ensure that 
any stacked lines are cleared. If the EXEC is named EXECl and is 
invoked with the line: 

execlttype help memottype print memo 

then the lines TYPE HELP MEMO and TYPE PRINT MEMO are cleared from the 
stack and are not executed. 

You could use the same technique to clear the stack in case of an 
error encountered in your EXEC, so that the stack is cleared before 
returning to CMS. You would especially want to do this if you stacked 
data lines or EXEC control statements that have no meaning to CMS. 

Another way to clear the console stack is with the CMS function 
DESBOF. For example: 

&IF SREADFLAG EQ STACK DESBUF 

ihen you use the DESBOF function to clear the console input stack, the 
output stack is also cleared. The output stack contains lines that are 
waiting to be displayed or typed at the terminal. Frequently, when an 
EXEC is processing, output lines are stacked, and are not displayed 
immediately following the execution of an STYPE statement. If you want 
to display all pending output lines before clearing the console input 
stack, you should use the CONWAIT function, as follows: 

CONHAIT 

SIF SREADFLAG EQ STACK DESBOF 

The CONHAIT (console wait) function causes a suspension of program 
execution until the console output stack is empty. If there are no lines 
waiting to be displayed, CONWAIT has no effect. 

Clearing the stack is important when you write edit macros, since all 
subcommands issued in an edit macro must be first stacked. See "Section 
17. Writing Edit Macros" for additional information on using the console 
stack- 
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File Manipulation with EXECs 



You can, to a liiDited degree, read and write CHS disk files using EXECs. 
You can stack files with a f iletype of EXEC in the console stack and 
then read them, one record at a tiae, with SREAD control statements. All 
data items are truncated to eight characters. You can write a file, one 
record at a time, with the SPONCH control statement, and then you can 
read the spool punch file onto disk. Examples of these techniques 
follow. 



STACKING EXEC FILES 



There are two methods to stack EXEC files in the console stack. One is 
illustrated using a CMS EXEC file, as shown in the following PREFIX 
EXEC: 

SLNAME = SCONCAT 61 * 

LISTFILE SLNAHE SCRIPT * (EXEC 

EXEC CMS &STACK 

SLOOP -END 6READFLAG EQ CONSOLE 

SREAD VARS SNAME STYPE SMOD 

SSUFFIX = SSOBSTR SNAME 3 6 

SNEHNAM = SCONCAT S2 SSUFFIX 

RENAME SNAME STYPE SMOD SNEHNAM STYPE SMOD 

SIF SRETCODE EQ SSKIP 

STYPE FILE SNAME STYPE NOT RENAMED 

-END 



This EXEC procedure is invoked with two arguments, each two characters 
in length, which indicate old and new prefixes for filenames. The EXEC 
renames files with a filetype of SCRIPT that have the first prefix, 
changing only the prefix in the filename. 



The LISTFILE command, invoked 
EXEC file in the format: 



with the EXEC option, creates a CMS 



SI S2 filename SCRIPT mode 

When the EXEC is invoked with the line: 

EXEC CMS SSTACK 

the argument SSTACK is substituted for the variable symbol S1 in each 
line in the CMS EXEC. The execution of the CMS EXEC effectively stacks, 
in the console stack, the complete file identifications of the files 
listed: 

SSTACK filename SCRIPT mode 
SSTACK filename SCRIPT mode 



These stacked lines are read back into the EXEC, one at a time, and the 
tokens "filename**, "SCRIPT", and "mode" are substituted for the variable 
symbols SNAME, STYPE, and SMOD. 

Using the SSUBSTR and SCONCAT built-in functions, the new name for 
each file is constructed, and the RENAME command is issued to rename the 
files. 



( 
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For example, if you invoke the EXEC procedure with the line: 

prefix ab xy 

all SCRIPT files that have filenames beginning with the characters AB 
are renamed so that the first two characters of the filename are XY. A 
sample execution summary of this EXEC is illustrated under "Debugging 
EXEC Procedures" in "Section 16. Refining Your EXEC Procedures." 



Stacking Data Files 

You can create a data file, containing fixed-length records, using a 
filetype of EXEC. To stack these data lines in the console stack, you 
can enter them following an &BEGSTACK (or SEEGSTACK ALL) control 
statement. For example, the file DATA EXEC is as follows: 

SBEGSTACK 
HARRY 10/12/48 
PATTI 1/18/49 
DAVID 5/20/70 
KATHY 8/6/43 
MARVIN 2/28/50 

The file BDAY EXEC contains: 

SCONTROL ERROR 

EXEC DATA 

&IF SREADFLAG EQ CONSOLE SGOTO -NO 

&READ VARS SNAME &DATE 

&IF SNAME NE SI SSKIP -2 

-FOUND 

SIF .SI EQ . SEXIT 

STYPE SI 'S BIRTHDAY IS SDATE 

CONWAIT 

DESBUF 

SEXIT 

-NO STYPE SI NOT IN LIST 

SEXIT 

When the BDAY EXEC is invoked, it expects an argument that is a first 
name. The function of the EXEC is to display the birthday of the 
specified person. A sample execution of this EXEC might be: 

bday kathy 

KATHY 'S BIRTHDAY IS 8/6/43 

R; 

BDAY EXEC first executes the DATA EXEC, which stacks names and dates 
in the console stack. Then, BDAY EXEC reads one line at a time from the 
stack, assigning the variable names SNAME and SDATE to the tokens on 
each line. It compares SNAME with the argument read as S1. When it finds 
a match, it displays the message indicating the date, and clears the 
console stack after waiting for terminal output to finish. 

Note that the file DATA EXEC begins with an SBEGSTACK control 
statement, but contains no SEND statement. The stack is terminated by 
the end of the EXEC file. "Writing Data Files" describes a technique 
you might use to add new names and birth dates to the DATA EXEC file. 
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Writing Data Files 

You can build a CMS file in your virtual card punch using the 8P0NCH and 
SBEGPONCH control statements. Depending on the spooling characteristics 
of your virtual punch, the file that you build may be sent to another 
user's card reader, or to your own virtual card reader. When you read 
the file with the CMS READCARD command, the spool reader file becomes a 
CMS disk file. 

The following example illustrates how you might use your card punch 
and reader to update a CMS file by adding records to the end of it. The 
file being updated is the DATA EXEC^ which is the input file for the 
BDAY EXEC, shown in the example in ''Stacking Data Files." You could 
create a separate EXEC to perform the update, but this example shows how 
you might modify the BDAY EXEC to perform the addition function 
(ellipses indicate the body of the EXEC, which is unchanged) : 

8C0NTR0L ERROR 

SIF G^ EQ ADD &GOTO -ADDNAME 



&EXIT 

-ADDNAME 

8TYPE ENTER FIRST NAME AND DATE IN FORM MM/DD/YY 

SHEAD VARS SNAME SDATE 

GIF .SNAME = . SSKIP 3 

&PONCH SNAME 6DATE 

STYPE ENTER NEXT NAME OR NOLL LINE: 

SSKIP -4 

CP SPOOL PUNCH TO * 

CP CLOSE PUNCH 

READCARD NEW NAMES ^ 

COPYFILE NEW NAMES A DATA EXEC A (APPEND \ 

SIF SRETCODE = SSKIP 2 

STYPE ERROR CREATING FILE 

SEXIT SRETCODE 

ERASE NEW NAMES 

When BDAY EXEC is invoked with the keyword ADD, you are prompted to 
enter lines to be added to the data file. Each line that you enter is 
punched to the card punch. When you enter a null line, indicating that 
you have finished entering lines, the CP commands SPOOL and CLOSE direct 
the spool file to your card reader and close the punch. 

The file is read in as the file NEW NAMES, which is appended to the 
file DATA EXEC using the COPYFILE command with the APPEND option. The 
file NEW NAMES is erased and the EXEC terminates processing. 



Using Your Virtual Card Punch 

When you punch lines in your virtual punch, the lines are not released 
as a CP spool file until the punch is closed. Since the EXEC processor 
does not close the virtual punch when it terminates processing, you must 
issue the CLOSE command to release the file. You can do this in the EXEC 
with the command line: 



CP CLOSE PUNCH 

or from the CMS environment after the EXEC has finished. If you use the 
CLOSE command in the EXEC, you must preface it with CP. 
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The CMS PUNCH command, which you can use in an EXEC to punch an 
entire CMS file, does close the punch after punching a file. Therefore, 
if you want to create a punch file using a combination of SPUNCH control 
statements and PUNCH commands, you must spool your punch using the CONT 
option, so that a close request does not affect the file: 

CP SPOOL PUNCH TO * CONT 

SPUNCH FIRST FILE 

&PUNCH 

PUNCH FILE1 TEST ( NOHEADER 

SPUNCH SECOND FILE 

SPUNCH 

PUNCH FILE2 TEST ( NOHEADER 

CP SPOOL PUNCH CLOSE NOCONT 

The preceding example punches title lines introducing the files punched 

with the CMS PUNCH command- The null SPUNCH statements punch blank 

lines. The PUNCH command is issued with the NOHEADER option, so that a 
read control card is not punched. 

You can also use an EXEC procedure to punch a job to send to the CMS 
batch facility for processing. The batch facility, and an example of 
using an EXEC to punch a job to it, are described in "Section 12. Using 
the CMS Batch Facility." 



Dsina SPUNCH and 6BEGPUNCH 



All lines punched to the virtual card punch are fixed-length, 
80-character records. When you use the SPUNCH control statement in a 
fixed-length EXEC file, EXEC scans only the first 72 columns of the 
EXEC. 

If you want to punch a word that contains more than eight characters, 
you must use the SBEGPUNCH control statement, which also, in 
fixed-length files, causes EXEC to punch data in columns 1 through 80. 



Jf 



Section 14. Building EXEC Procedures 297 



< 



298 IBM VM/370 CMS User's Guide 



1 



Section 15. Using EXECs with CMS Commands 



Whenever you create an EXEC file you are, for all practical purposes, 
creating a new CHS conmand. When you enter a command line in the CHS 
environment, CHS searches for an EXEC file with the specified filename 
before searching for a HODDLE file or CHS command. You can place the 
names of your EXEC files in a synonym table and assign minimum 
truncation values for the synonyms, just as you can for CHS command 
names. 

While many of your EXEC procedures may be very simple, others may be 
very long and complicated, and perform many of the housekeeping 
functions performed by CHS commands, such as syntax checking, error 
message generation, and so on. 

Monitoring CMS Command Execution 

Hany, or most, of your EXEC procedures may contain sequences of CHS 
commands that you want to execute. If your EXEC procedure contains no 
EXEC control statements, each command line is displayed and then the 
command is executed. If an error occurred, the CHS error message is 
displayed, followed by a return code in the format: 

♦++ R (nnnnn) **+ 

where nnnnn is the nonzero return code from the CHS command. If the 
command is not a valid CHS command, or the command function for SET or 
QUERY is invalid and the implicit CP function is in effect, the return 
code is a -3: 

+++ R(-0003) ♦++ 

You may also receive this error return when you use a CF command without 
prefacing it with the CP command. If you enter an unknown CP command 
following "CP", you receive a return code of 1. 

If a command completes successfully, no return code is displayed. 

If you do not want to see the command lines displayed before 
execution, nor return codes following execution, you can use the EXEC 
control statement: 

SCONTROL OFF 

Or, if you want to see only the command lines that produced errors, and 
the resultant return codes, you can specify: 

&CONTROL ERROR 

Regardless of these settings of the &CONTROL statement, CHS error 
messages are displayed, as long as the value of 8READFLAG is RT, and the 
terminal is displaying output. 

If you issue the LISTFILE, STATE, ERASE, or RENAHE commands in an 
EXEC procedure, and you do not want to see the error message FILE NOT 
FOUND displayed, you can use the statement: 

&CONTROL NOHSG 

to suppress the display of these particular messages. 
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You can request that particular timing information be displayed 
during an EXEC's execution- If you want to display the time of day at 
which each command executes, you can specify: 

8C0NTR0L TIME 

Then, as each command line is displayed, it is prefaced with the time; 
for example: 

SCONTROL CMS TIME 
QUERY BLIP 

executes as follows: 

10:34:16 QUERY BLIP 
BLIP = * 

If you wish to see, following the execution of each CMS command, 
specific CPU timing information, such as the long form of the ready 
message, you can use the 6TIME control statement. For example: 

STIME ON 
QUERY BLIP 
QUERY FILEDEF 

might execute as: 

QUERY BLIP 
BLIP = OFF 
T=0.01/0.04 10:44:21 

QUERY FILEDEF 

NO USER DEFINED FILEDEF* S IN EFFECT 

T=0. 01/0,04 10:45:26 

Handling Error Returns from CMS Commands 

In many cases, you want to execute a command only if previous commands 
were successful. For example, you would not want to execute a PRINT 
command to print a file if you had been unable to access the disk on 
which the file resided. There are two methods, using EXEC procedures, 
that allow you to monitor and control what happens following the 
execution of CMS commands. One method uses the EXEC control statement 
SERROR to transfer control when an error occurs; the other tests the 
special variable SRETCODE upon completion of a CMS command to determine 
whether that particular command completed successfully. 

USING THE SERROR CONTROL STATEMENT 

When a CMS command is executed within an EXEC, a return code is passed 
to the EXEC interpreter, indicating whether or not the command completed 
successfully. If the return code is nonzero, EXEC then activates the 
&ERROR control statement currently in effect- For example, if the 
following statement is included at the beginning of an EXEC file: 

SERROR SEXIT 

then, whenever a CMS command (or user program) completes with a nonzero 
return code, the 8EXIT statement in the SERROR statement is executed, 
and the EXEC terminates processing. You might use a similar statement 
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in your EXECs to ensure that they do not attempt to continue processing 
in the event of an error. 

An &ERROR control statement can specify any executable statement. It 
nay transfer control to another portion of the EXEC, or it many be a 
single statement that executes before control is returned to the next 
statement in the EXEC. For example: 

SERROR SGOTO -EXIT 

transfers control to the label -EXIT, in case of any CMS error. The 
statement: 

SERROR 6TYPE CMS ERROR 

results in the display of the message "CMS ERROR" before returning 
control to the statement following the command that caused the error. 

If you do not have an SERROR control statement in an EXEC, or if you 
specify SERROR with no operands, EXEC takes no special action when a CMS 
command returns with an error return code- Specifying SERROR with no 
operands is the same as specifying: 

SERROR SCONTINDE 

Since an SERROR control statement remains in effect for the remainder 
of the EXEC execution, or until another SERROR control statement is 
encountered, you may use SERROR SCONTINOE to restore default processing. 



USING THE SRETCODE SPECIAL VARIABLE 

An error return from a CMS command, in addition to calling an SERROR 
control statement, also places the return code value in the EXEC special 
variable SRETCODE. Following the execution of any CMS command in an 
EXEC procedure, you can test whether or not the command completed 
without error. For example: 

TYPE ALPHA FILE A 

SIF SRETCODE -i= SEXIT 

TYPE BETA FILE A 

SIF SRETCODE -^= SEXIT 

Note that the value of SRETCODE is modified after the execution of each 
CMS command. 

The value of SRETCODE is affected by your own programs. If you 
execute a program in your EXEC using the LOAD and START (or FETCH and 
START) commands, or if you execute a MODOLE file, then the SRETCODE 
special variable contains whatever value was in general register 15 when 
the program exited. If you are nesting EXEC procedures, then SRETCODE 
contains the value passed from the SEXIT statement of the nested EXEC. 

You can use the value of the return code, .as well, to analyze the 
extent or the cause of the error and to set up an error analysis routine 
accordingly. For example, suppose you want to set up an analysis 
routine to identify return codes 1 through 11 and to exit from the EXEC 
when the return code is greater than 11. Uhen a return code is 
identified, control is passed to a corresponding routine that attempts 
to correct the error. You could set up such an analysis routine as 
follows: 
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-ERRANAL 

SCNT = 

SLOOP 2 8CNT EQ 12 

&IF 6RETC0DE EQ GCNT &GOTO -FIXSCNT 

8CNT = 8CNT +1 



-FIXO 8G0T0 -ALLOK 
-FIX1 



8G0T0 -ALLOK 
-FIX2 



8G0T0 -ALLOK 
-FIX11 

-ALLOK 

Hhen the value of the 8CNT variable equals the return code value in 
6RETC0DE, the branch to the corresponding -FIX routine is taken. Each 
corrective routine performs different actions, depending on its code, 
and finishes at the routine labeled -ALLOK. 

You can, in sone cases, determine the cause of a CMS command error 
and attempt to correct it in your EXEC. To do this, you must know the 
return codes issued by VM/370 commands. See VH/370 System Messages for a 
discussion of the return codes for VM/370 commands. In addition, the 
error messages and corresponding return codes are listed under the 
command descriptions for each CMS command in the VM/370 CMS Command and 
l|ac£5 l6f6£ Slice. 

As an example, all CHS commands that search for files issue a return 
code of 28 when a file is not found. If you want to test for a 
file-not-found condition in your EXEC, you might use statements similar 
to the following: 

8C0NTR0L OFF NOMSG 



TYPE HELP MEMO A 

SIF 8RETC0DE = 28 8G0T0 -NOFILE 

Tailoring CMS Commands for Your Own Use 

You can create EXEC procedures that simplify or extend the use of a 
particular CMS command. Depending on your applications, you can modify 
the CMS command language to suit your needs. You can create EXEC files 
that have the same names as CMS commands, and, since CMS locates EXEC 
files before MODULE files, the EXEC is found first. For example, the 
COPYFILE command, when used to copy CMS disk files, requires six 
operands. If you change only the filename when you copy files, you could 
create a COPY EXEC as follows: 
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SCONTROL OFF 

&IF &INDEX -.= 3 6SKIP 2 

COPYFILE &1 S2 = S3 &2 = 

&EXIT 

COPYFILE &1 &2 &3 &U S5 &6 87 &8 69 810 811 812 813 814 815 

If you always invoke the COPYFILE command using the truncation COPY, 
EXEC processes the command line for you, and if you have entered the 
three arguments, EXEC formats the COPYFILE command for you. If any 
other number of arguments is entered, the COPYFILE command is invoked 
with all the arguments as entered. 

CREATING YOOR OWN DEFAULT FILETYPES 

If you use special filetypes for particular applications and they are 
not among those that the CMS editor supplies default settings for, but 
do require special editor settings, you can create an EXEC to invoke the 
editor. The EXEC can check for particular filetypes, and if it finds 
them, stack the appropriate EDIT subcommands. If you name this EXEC 
procedure E EXEC, then you can bypass it by using a longer form of the 
EDIT command. The following is a sample E EXEC: 

8C0NTR0L OFF 

8IF 8INDEX GT 1 &SKIP 2 

EDIT 81 SCRIPT 

8EXIT 

8IF 82 EQ TABLE 6G0T0 -TABLE 

8IF 82 EQ CHART 8G0T0 -CHART 

8IF 82 EQ EXEC &GOTO -EX 

8IF 82 EQ SYSIN 8G0T0 -SYSIN 

-NORM EDIT 81 82 83 84 85 66 

6EXIT 

-TABLE 6BEGSTACK 

IMAGE ON 

TABS 1 10 20 

CASE M 

8END 

EDIT 81 82 83 (LRECL 20 

&EXIT 

-CHART 6BEGSTACK 

CASE M 

IMAGE ON 

8END 

EDIT 61 62 63 

8EXIT 

-EX 

EDIT 81 82 83 (LRECL 130 

8EXIT 

-SYSIN 8BEGSTACK 

TABS 1 10 16 31 36 41 46 69 72 80 

SERIAL ON 

TRUNC 71 

VERIFY 72 

8END 

EDIT 81 82 83 

6EXIT 

This EXEC defines special characteristics for filetypes CHART, TABLE, 
and SYSIN, and defaults an EXEC file to 130-character records. If only 
one argument is entered, it is assumed to be the filename of a SCRIPT 
file. Since the editor is invoked from within the EXEC, control returns 
to EXEC after you use the FILE or QUIT subcommands during the edit 
session. You must use the 8EXIT control statement so that the EXEC does 
not continue processing, and execute the next EDIT command in the file. 
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Section 16. Refining Your EXEC Procedures 







This section pi^ovides supplementary information for writing complex EXEC 
procedures. Although the EXEC interpreter resembles, in some aspects, a 
high-level programming language, you do not need to be a programmer to 
write EXECs. Some of the techniques suggested here, for example, on 
annotating and writing error messages, are common programming practices, 
which help make programs self-documenting and easier to read and to use. 

Annotating EXEC Procedures 

Lines in an EXEC file that begin with an asterisk (*) are commentary and 
are treated as comments by the EXEC interpreter. You can use * 
statements to annotate your EXECs. If you write EXECs frequently, you 
may find it convenient to include a standard comment at the beginning of 
each EXEC, indicating its function and the date it was written, for 
example: 

* EXEC TO HELP CONVERT LISTING FILES 

* INTO SCRIPT FILES 

* J. BEAN 10/18/75 

You can also use single asterisks or null lines to provide spacing 
between lines in an EXEC file to make examining the file easier. 

In an EXEC, you cannot place comments on the same line with an 
executable statement. If you want to annotate a particular statement or 
group of statements, you must place the comments either above or below 
the lines you are annotating. 

A good practice to use, when writing EXECs, is to set them up to 
respond to a ? (question mark) entered as the sole argument. For 
example, an EXEC named FSORT might contain: 

SCONTROL OFF 

SIF 8INDEX = 1 &IF 81 = ? SGOTO -TELL 



-TELL &BEGTYPE 

CORRECT FORM IS • FSORT USERID <VADDR> • 

PRINTS AN ALPHABETIC LISTING OF ALL FILES ON THE SPECIFIED 
USER'S DISK. IF A VIRTUAL ADDRESS (VAEDR) IS NOT 
SPECIFIED, THE USER'S 191 IS THE DEFAULT. 
SEND 

You may also wish to anticipate the situation in which a user might 
enter an EXEC name with no arguments for an EXEC that requires 
arguments: 
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SIF 8INDEX = SGOTO -HELP 

8IF SINDEX = 1 SIF 81 = ? 8G0T0 -TELL 



&EXIT 

-HELP 8BEGTYPE 

CORRECT FORM IS • COPY OLDFN OLDFT NEHFN » 

TYPE • COPY ? • FOR MORE INFO 
8END 
8EXIT 
-TELL 8BEGTYPE 

CORRECT FORM IS 'COPY OLDFN OLDFT NEWFN • 

USES COPYFILE COMMAND TO CHANGE ONLY THE FILENAME 
&END 
8EXIT 

This type of annotating is especially useful if you share your disks or 
your EXECS with other users. 

Error Situations 

It is good practice, when writing EXECs, to anticipate error situations 
and to provide meaningful error or information messages to describe the 
error when it occurs. The following error situations, and suggestions 
for handling them, have already been discussed: 

• Errors in invoking the EXEC, either with an improper number of 
arguments, or with invalid arguments. (See "Arguments" in "Section 
14. Building EXEC Procedures.") 

• Errors in CMS command processing that can be detected with an 8ERR0R 
control statement or with the 8RETC0DE special variable. (See 
"Handling Error Returns from CMS Commands" in "Section 15. Using 
EXECs With CMS Commands.") 

Many different kinds of errors may also occur, in the processing of 
your EXEC control statements. EXEC processing errors, such as an attempt 
to branch to a nonexistent label or an invalid syntax, are 
"unrecoverable" errors. These errors always terminate EXEC processing 
and return your virtual machine to the CMS environment or to the calling 
EXEC procedure or program. The error messages produced by EXEC, and the 
associated return codes, are described in the YM/370 System Messages. 



WRITING ERROR MESSAGES 

One way to make your EXECs more readable, especially if they are long 
EXECs, is to group all of your error messages in one place, probably at 
the end of the EXEC file. You may also wish to number your messages and 
associate the message number with a label number and a return code. For 
example: 



i 
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SIF 6CT > 100 &GOTO -ERR100 
&IF &CT < SGOTO -ERR200 



SIF SRETCODE EQ 28 SGOTO -ERR300 



-ERR100 

STYPE COUNT TOO HIGH 

SEXIT 100 

-ERR200 

STYPE COUNT TOO LOW 

SEXIT 200 

-ERR300 

STYPE SI S2 NOT ON DISK 

SEXIT 300 



Using the SEMSG Control Statement 

There is a facility, available in the EXEC processor, which allows you 
to write error messages that use the standard VM/370 message format, 
with an identification code and message number, as well as message text. 
When you use the SEMSG or SBEGEMSG control statement, the EXEC 
interpreter scans the first token and checks to see if the seventh (and 
last character) is an I, E, or H, representing information, error, or 
warning messages, respectively. If so, then the message is displayed 
according to the CP EMSG setting (ON, OFF, CODE, or TEXT) . For example, 
if you have the statement: 

SEHSG ERRORIE BAD ARGUMENT • SI • 

the ERRORIE is considered the code portion of the message and BAD 
ARGUMENT is the text. If you have issued the CP command: 

cp set emsg text 

when this SEMSG statement is executed it may display: 

BAD ARGUMENT * PRNIT • 

where PRNIT is the argument that is invalid. 

When you use SEMSG (or SBEGEMSG, which allows you to display error 
messages of unscanned data) , the code portion of the message is prefixed 
with the characters DMS, when displayed- For example: 

SBEGEMSG 

ERR0R2E INCOMPATIBLE ARGUMENTS 

SEND 

displays when the EMSG setting is ON: 

DMSERR0R2E INCOMPATIBLE ARGUMENTS 

You should use the SBEGEMSG control statement when you want to display 
lines that have tokens longer than eight characters; however, no 
variable substitution is performed. 
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Debugging EXEC Procedures 

If you have difficulty getting an EXEC procedure to execute properly, or 
if you are modifying an existing EXEC and wish to test it, there are a 
couple of simple techniques that you can use that may save you time. 

One is to place the 8C0NTR0L ALL control statement at the top of your 
EXEC file. When 8C0NTR0L ALL is in effect, all the EXEC control 
statements are displayed before they execute, as well as the CMS command 
lines. One of the advantages of using this method is that the line is 
displayed after it is scanned, so that you can see the results of symbol 
and variable substitution. 

"Stacking EXEC Files" in "Section 14. Building EXEC Procedures" 
described a PREFIX EXEC, which changes the prefixes of groups of files. 
If the EXEC had an 8C0NTR0L ALL statement, it might execute as follows: 

prefix pt ag 

SCONTROL ALL 

&LNAME = SCONCAT PT * 

LISTFILE PT* SCRIPT * ( EXEC 

EXEC CMS &STACK 

SLOOP -END 8READFLA EQ CONSOLE 

LOOP UNTIL: STAC K EQ CONS 

SREAD VARS &NAME 8TYPE 8M0D 

8S0FFIX = 8SUBSTR PTA 3 6 

&NEWNAM = SCONCAT AG A 

RENAME PTA SCRIPT A1 AGA SCRIPT A1 

SIF EQ 8SKIP 

SSKIP 

LOOP UNTIL: STAC K EQ CONS 

SREAD ?ARS SNAME STYPE SMOD 

SSUFFIX = SSUBSTR PTB 3 6 

SNEWNAM = SCONCAT AG B 

RENAME PTB SCRIPT Al AGB SCRIPT Al 

SIF EQ SSKIP 

SSKIP 

LOOP UNTIL: CONS OLE EQ CONS 

R; 

You can see from this execution summary that the files named PTA SCRIPT 
and PTB SCRIPT are renamed to AGA SCRIPT and AGB SCRIPT. Notice that 
the SLOOP statement results in a special LOOP UNTIL statement in the 
execution summary, which indicates the condition under which the loop 
executes. 



USING CMS SUBSET 

When you are using the CMS editor to create or modify an EXEC procedure, 
you can test the EXEC in the CMS subset environment, as long as the EXEC 
does not issue any CMS commands that are invalid in CMS subset. 

Before entering CMS subset with the CMS subcommand, you must issue 
the SAVE subcommand to write the current version of the EXEC onto disk; 
then, in CMS subset, execute the EXEC. For example: 
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edit new exec 

NEW FILE: 

EDIT: 

input 

INPUT: 

&a = S1 ♦ &2 + S3 

&type answer is &a 

EDIT: 

save 

EDIT: 

ens 

CMS SUBSET 

new 34 56 899 

ANSWER IS 989 

R; 

return 
EDIT: 
quit 

R; 

If the EXEC does not execute properly, you can return to the edit 
environment using the RETURN conmand, modify the EXEC, reissue the SAVE 
and CHS subcommands, and attempt to execute the EXEC again. 



SUMMARY OF EXEC INTERPRETER LOGIC 

The following information is provided for those who have an interest in 
how the EXEC interpreter works. It may help you in debugging your EXEC 
procedures if you have some idea of how processing is done by EXEC. 
When an EXEC file is invoked for execution, the EXEC interpreter 
''\ examines each statement and analyzes it, according to the following 

sequence: 

1. If the first nonblank character of the line is an *, the line is 
counted and ignored. 

2. Null lines, except as a reponse to an SREAD statement, are also 
counted and ignored. 

3. The line is scanned, and nonblank character strings are placed in 
tokens. 

4. All EXEC special variables, and then all user variables, except for 
those that appear as the target of an assignment statement, are 
substituted. 

6. All blank tokens (resulting from the substitution of undefined 
symbols) are discarded. 

7. If the first nonblank character is a hyphen (-) , indicating a 
label, the next token is considered the first token. 

8. If the first logical token does not begin with an ampersand (S) , 
the line is passed to CMS for execution. The' return code from CMS 
is placed in the special variable &RETCODE. 

9. If the first logical token begins with an ampersand (S) EXEC 
interprets the statement. 

10. If a statement is syntactically invalid and can be made valid by 
adding a token of blanks at the end, EXEC adds blanks, for example: 
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SBLANK = 

STYPE 

SLOOP 3 &X NE 

All of the above are valid EXEC control statements. 

11. EXEC executes the statement. If no error is encountered, control 
passes to the next logical statement. If an error is encountered, 
EXEC terminates processing. 



< 
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If you have a good 
understanding of the CM 
edit macro is simply 
subcommands. Edit macro 
An edit macro may conta 
execution may be depen 
This section provides 
on how to manipulate th 
you can create and use. 



knowledge of the CMS EXEC facilities and an 
S editor, you may wish to write edit macros. An 
an EXEC file that contains a sequence of EDIT 
s can only be invoked from the edit environment, 
in a simple sequence of EDIT subcommands, or its 
dent on arguments you enter when you invoke it. 
information on creating edit macros, suggestions 
e console stack, and some examples of macros that 



Creating Edit Macro Files 



An edit macro must have a filename beginning with a dollar sign ($) and 
a filetype of EXEC. Rules for file format, scanning and token 
substitution are the same as for all other EXEC files. A macro file may 
contain: 



I 



• EDIT subcommands 

• EXEC control statements 

• CHS commands that are valid in CHS subset 

When you create an edit macro that accepts arguments, you should be 
sure to check the validity of the arguments, and issue appropriate error 
messages. If you are writing an edit macro to expect arguments, you must 
keep in mind that the macro command line is scanned, and that any data 
items you enter are padded or truncated into eight-character tokens. 
Tokens are always translated to uppercase letters. 



You should annotate all of your macro files, and provide a response 
to a question mark (?) entered as the sole argument (as described under 
"Annotating EXEC Procedures" in "Section 16. Refining Your EXEC 
Procedures") . 



How Edit Macros Work 



Since an edit macro is an EXEC file, it is actually executed by the EXEC 
interpreter, and not by the editor. The EXEC interpreter can only 
execute EXEC control statements and CHS commands. The only way to issue 
an EDIT subcommand from an EXEC file is to stack the subcommand in the 
console stack, so that when the editor is invoked, or receives control, 
it reads the subcommand (s) from the console stack before accepting input 
lines from the terminal. For example: 

SSTACK CASE M 
SSTACK RECFH V 
EDIT SI CHART A1 



When the EDIT command is invoked from this EXEC, the editor 
subcommands from the stack and executes them. 



reads the 






To execute these same subcommands from an edit macro file, you must 
use the same technique; that is, you must place the subcommands - in the 
console stack, for example: 
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SBEGSTACK 
CASE M 
RECFM V 
SEND 
8EXIT 

If this vere an EXEC file named $VARY, you might execute it from the 
edit environment as follows: 

edit test file 
NEW FILE. 
EDIT: 
$vary 

Stacked subcommands are executed only when the EXEC completes its 
execution, either by reaching the end of the file, or by processing an 
6EXIT statement. 

When you stack EDIT subcommands, you can use the &STACK and &BEGSTACK 
control statements. If you are stacking a subcommand that uses a 
variable expression, you must use the ©STACK control statement, rather 
than the &BEGSTACK control statement. The following EXEC, named $T, 
displays a variable number of lines and then restores the current line 
pointer to the position it was in when the EXEC was invoked: 

©CONTROL OFF 

SIF &INDEX EQ SGOTO -ERR 

SCHECK = SDATATYPE 61 

SIF SCHECK NE NDM SGOTO -ERR 

SSTACK TYPE S1 

SOP = S1 - 1 

SSTACK UP SOP 

SEXIT 

-ERR STYPE CORRECT FORM IS < $T N > 

SEXIT 1 

This edit macro uses the built-in function SDATATYPE to check that a 
numeric operand is entered. 

CMS commands in an edit macro are executed as they are read by the 
EXEC interpreter, just as they would if the EXEC were invoked in the CBS 
environment. You could create a $TYPE edit macro, for example, that 
would allow you to display a file from the edit environment: 

SCONTROL OFF 

TYPE SI S2 S3 SU S5 S6 S7 

Or you might create a $STATE EXEC that would verify the existence of 
another file: 

SCONTROL OFF 
STATE SI S2 S3 

In both of these examples, the macro file invokes the CMS command. 
Macros like these can eliminate having to enter CMS subset environment 
to execute one or two simple CMS commands. You must be careful, though, 
not to execute any CMS command that uses the storage occupied by the 
editor. Only commands that are valid in CMS subset are valid in an edit 
macro. 
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THE CONSOLE STACK 

When you write an edit nacro, you want to be sure that there are no EDIT 
subcommands in the stack that could interfere with the execution of the 
subcommands stacked by the macro file. Your macro should check whether 
there are any lines in the stack, and if there are, it should clear them 
from the stack. For example, you might use the lines: 

SIF SREADFLAG EQ CONSOLE 8SKIP 2 

DESBDF 

STYPE STACKED LINES CLEARED BY SO 

The message "STACKED LINES CLEARED BY macro name" is issued by the edit 
macros distributed with the VM/370 system. You may also want to use 
this convention in your macros, to alert a user that the console stack 
has been cleared. 



122 of File and End of File 

When an edit macro is invoked and the current line pointer is positioned 
at the top of the file or at the end of the file, the editor stacks a 
token in the console stack. If the line pointer is at the top of the 
file, the token stacked is "TOF"; if the line pointer is at the end of 
the file the token stacked is "EOF". If you write an edit macro that 
does not check the status of the console stack, and the macro is invoked 
from the top or the end of the file, you receive the message: 

?EDIT: TOF 
or: 

?EDIT: EOF 

The editor does not recognize these tokens as valid subcommands. 

You may want to use these tokens to test whether the EXEC is invoked 
from the top or end of the file. If you want to clear these tokens in 
case the macro has been invoked from the top or end of the file, you 
might use the statement: 

&IF &READFLAG EQ STACK SREAD ARCS 

which clears the token from the stack. 



Stacking LIFO 

If you do not want to clear the console stack when you execute an edit 
macro, you can stack all of the subcommands using the LIFO (last-in 
first-out) operand of the &STACK and &BEGSTACK control statements. For 
example, suppose $FORMAT is the name of the following edit macro: 

&BEGSTACK LIFO 
TABSET 3 10 71 
TRUNC 71 
PRESERVE 
&END 
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When this edit macro is executed, the subcommands are placed in the 
console stack in front of any existing lines. For example, if this macro 
were invoked: 

$format#input 

the subcommands would execute in the following order: PRESERVE, TRONC, 
TABSET, INPUT. If the subcommands were stacked FIFO (first-in 
first-out) , the default, the INPUT subcommand would be the first to 
execute (since it is the first command in the stack) and the remaining 
subcommands would be read into the file as input lines. 



^rror Situations 

If an EXEC processing error occurs during the execution of an edit 

macro, the editor clears the console stack and issues the "STACKED LINES 

CLEARED'* message. An EXEC processing error is one that causes the error 
message DMSEXT072E: 

ERROR IN EXEC FILE filename, LINE nnnn - description 

These errors cause the EXEC interpreter to terminate processing. Any 
stacked subcommands are cleared before the editor regains control, so 
that none of the subcommands are executed, and the file remains 
unchanged. 

You should also ensure that any error handling routines in your edit 
macros clear the stack if an error occurs. Otherwise, the editor may 
begin reading invalid data lines from the stack and attempt to execute 
them as EDIT subcommands. 

You should not interrupt the execution of an edit macro by using the 
Attention or Enter key, and then entering a command or data line. 
Results are unpredictable, and you may inadvertently place unwanted 
lines in the stack. 

If your edit macro contains a CMS command that is invalid in the CBS 
subset environment, you receive a return code of -2. 

The maximum number of lines that you can stack in an edit macro 
varies according to the amount of free storage that is available to CBS 
at the time of the stacking request. If you stack too many lines, the 
editor terminates abnormally. 

Notes on Using EDIT Subcommands 

You can use any EDIT subcommand in a macro file, and there is one 
special subcommand whose use only has meaning in a macro: the STACK 
subcommand. For the most part, there is not any difference between 
executing an EDIT subcommand from the edit environment, or from an EXEC 
edit macro. You do have to remember, however, that if you want a 
variable symbol on a subcommand line, you must stack that subcommand 
using the 6STACK control statement rather than following an 8BEGSTACK 
control statement. 

Listed below are some notes on using various EDIT subcommands in your 
macro files. You may find these notes useful when you design your own 
macros. 
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ilJSERVE, IMIZIr Ml IISTORE: Often, you aay want to create an edit 
macro that alters the characteristics of a file (format, tab settings, 
and so on) . To ensure that the original characteristics are retained 
when the macro has finished executing, you can stack the PRESERVE 
subcommand as the first subcommand in the stack, and the RESTORE 
subcommand as the last subcommand in the stack: 

SBEGSTACK 

PRESERVE 

CASE M 

I A lowercase line 

RESTORE 

&END 

The PRESERVE and RESTORE subcommands save and reinitialize the settings 
for the CASE, FMODE, FNAME, IMAGE, LINEMODE, LONG, RECFH, SERIAL, SHORT, 
TABSET, TRONC, VERIFY, and ZONE subcommands. 

In an edit macro that issues many subcommands that display lines in 
response to CHANGE or LOCATE subcommands, you may want to turn the 
verification setting to OFF to suppress displays during the execution of 
the edit macro: 

SBEGSTACK 
PRESERVE 
VERIFY OFF 



RESTORE 
SEND 

You would particularly want to turn verification off for a macro that 
I executes in a loop or that issues a global request. If you want a line 
p or series of lines displayed, you can use the TYPE subcommand. 

If you have verification set off in an edit macro, then when you 
execute it you may not receive any indication that the edit macro 
completed execution. The keyboard unlocks to accept your next EDIT 
subcommand from the terminal. To indicate that the macro is finished, 
you can stack, as the last subcommand in the procedure, a TYPE 
subcommand, to display the current line. Or, if you write an edit macro 
that terminates when an end-of-file condition occurs the EOF: message 
issued by the editor may indicate the completion of the macro. 

INPUT, REPLACE: To change from edit mode to input mode in an edit macro, 
you can use the INPUT and REPLACE subcommands. In a fixed-length EXEC 
file, you must stack these subcommands using the 8STACK control 
statement: 

5STACK INPUT 

— or — 

SSTACK REPLACE 

If you use either of these subcommands following an SBEGSTACK control 
statement, the subcommand line is padded with blanks to the line length 
and the result is a line of blanks inserted into the file. 

In a variable- length EXEC file, lines are not padded with blanks, so 
the INPUT and REPLACE subcommands with no data line execute the same 
following an SBEGSTACK control statement as they do when stacked with 
%k the SSTACK control statement. 
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Going From Infut Mode to Edit Mode: To stack a null line in an edit 
macro, to cause the editor to leave input mode, you nust use the 8STACK 
control statement with no other tokens, as follows: 

SSTACK 

CHANGE, DSTRING, LOCATE: If you want to use the CHANGE, DSTHING, or 
LOCATE subcommands'"in"'an EXEC, you must take into account that when you 
stack any of these subcommands using the &STACK control statement, all 
of the character strings on the line are truncated or padded to eight 
characters. Also, if you want to use a variable value for a character 
string, you are limited to eight characters, all uppercase. 

For example, if a macro is used to locate a character string and 
delete the line on which it appears, the LOCATE subcommand has a 
variable symbol: 

SSTACK LOCATE /SI 
SSTACK DEL 

IMAGE, TABSET, QVEfiLAY: The TABSET and OVERLAY subcommands allow you to 
set margins and column stops for records in a file and to overlay 
character strings in particular positions. For example, the following 
macro places a vertical bar in columns 1, 15, HO, and 60 for all records 
in the file from the current line to the end of the file: 

8BEGSTACK 

PRESERVE 

IMAGE ON 

TABSET 1 15 40 60 

REPEAT * 

|->|->|->| 

RESTORE 
SEND 

In the above example, the •»->" symbol represents a tab character 
(X»05»). To create this EXEC, you can either issue the EDIT subcommand: 

image off 

and use the Tab key (or equivalent) on your terminal when you enter the 
line, or you can enter some other character and use the ALTER subcommand 
to alter that character to a X»05'. 

If you want to overlay only one character string in a particular 
position in a file, you can use the TABSET subcommand to set that column 
position as the left margin, and then use the OVERLAY subcommand, as 
follows: 

SCONTROL OFF 

SBEGSTACK 

PRESERVE 

VERIFY OFF 

TRDNC * 

TABS 72 

SEND 

SSTACK REPEAT S1 

SBEGSTACK 

OVERLAY C 

RESTORE 

SEND 



( 
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If you name this file $CONT EXEC, and if you invoke it with the line: 

$cont 3 

then the OVERLAY subcoimand is executed on three successive lines, to 
place the continuation character "C" in column 72. 



THE STACK SOBCOMMAND 

The STACK subcommand allows you to stack up to 25 lines from a file in 
the console stack. The lines are not deleted from the file, but the line 
pointer is moved to point to the last line stacked. 

You can also use the STACK subcommand to stack EDIT subcommands. You 

might do this if there were subcommands that you wanted to place in the 

stack to execute after all the subcommands stacked by the EXEC had 
executed. 

These techniques are used in the two edit macros that are distributed 
with the VM/370 system: $MOVE and SDUP. If you want to examine these 
files for examples of how to use the STACK subcommand, you can display 
the files by entering, from the CMS environment: 

type $move exec * 

type $dup exec * 

An additional use of the STACK subcommand is shown in "An Annotated 
Edit Macro." 
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An Annotated Edit Macro 



The edit macro shown below, $DOUBLE, can be used to double space a CMS 
file. Regardless of where the current line pointer is, a blank line is 
inserted in the file following every existing line. The statements in 
the edit macro are separated into groups; the number to the left of a 
statement or group of statements indicates an explanatory note. The 
numbers are not part of the EXEC file. 



1 SCONTROL OFF 

2 SIF SINDEX = 1 SIF 81 = ? SGOTO -TELL 

3 SIF SINDEX = 1 SIF S1 = TWO SGOTO -LOOP 
^ SIF SINDEX NE SGOTO -TELL 

5 SIF SREADFLAG EQ STACK SREAD 7ARS SGARB 

6 SSTACK 

SSTACK PRESERVE 
SSTACK VERIFY OFF 

7 SSTACK BOTTOM 
SSTACK I XXXXXXXX 
SSTACK TOP 



Notes: 

1 The SCONTROL statement suppresses the display of CMS commands, in 
this case, the DESBOF command. 

2 The first SIF checks that there is only one operand passed in the 
$DODBLE command. The second SIF checks whether $DO0BLE has been 
invoked with a question mark (?) . If both SIFs are true, control 
is passed to the statement at the label -TELL. STYPE control 
statements at -TELL explains what the macro does. 

3 The second SIF statement checks whether IDOOBLE has been invoked 
with the argument TWO, which indicates that the macro has executed 
itself, so the subcommands that initialize the file are stacked 
only once. 

4 There are three ways to properly invoke this edit macro: with a ?, 
with the argument TWO, or with no arguments. The third SIF 
statement checks for the (no arguments) condition; if the macro is 
invoked any other way, control is passed to the label -TELL, which 
explains the macro usage. 

5 The SREADFLAG special variable is checked. If $DODBLE is executed 
at the top or at the end of the file, the token TOF or EOF is in 
the stack, and should be read out. 

6 A null line is placed in the console stack for loop control (see 
Note 9.) The PRESERVE and VERIFY subcommands are stacked so that 
the editor does not display each line in the file as it executes 
the stacked subcommands. 

7 The BOTTOM, INPUT, and TOP subcommands initialize the file by 
placing a marker at the bottom of the file, and then positioning 
the current line pointer at the top of thfe file. 



i 
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8 -LOOP 
&BEGSTACK 
NEXT 
STACK 1 
INPUT 
&END 

9 SREAD ARCS 

&IF .£1 = . &SKIP 

SIF SI EQ XXXXXXXX SSKIP 2 

10 -ENDLOOP &STACK $DODBLE TWO 

11 &EXIT 

12 DESBUE 
&BEGSTACK 
UP 2 

DEL 3 
TYPE 
RESTORE 
SEND 

SEXIT 

13 -TELL 

SIF SREADFLAG EQ STACK SREAD VARS 

SBEGTYPE 

CORRECT FORM IS: $DOUBLE 

THIS EXEC DOUBLE SPACES A FILE BY INSERTING 
A BLANK LINE FOLLOWING EVERY LINE IN THE FILE 
EXCEPT THE LAST. 
&END 



8 The NEXT, STACK, and INPUT subcommands are going to be repeated for 
each line in the £ile» The INPUT subcommand with no data line 
stacks a null line. Note that in order for $DOUBLE to execute this 
subcommand properly, $DOUBLE EXEC must have fixed-length records. 
Each line is stacked, with the STACK subcommand; this stacked line 
is checked in the read loop (Note 9) . When the stacked line is 
equal to the marker, XXXXXXXX, it indicates that the end of the 
file has been reached. 

9 These lines check for an end of file, which occurs when the line 
containing the marker is read. The first time this loop is 
executed, the stack contains the null line (statement 6) , so the 
check for the marker is skipped. 

10 The last subcommand stacked is $DOUBLE TWO, which re-invokes 
$DOUBLE, but causes it to skip the first sequence of subcommands. 

11 The &EXIT statement causes an exit from $EOUBLE, so that all the 
EDIT subcommand stacked thus far are executed. 

12 When the marker is read in, the EXEC clears the stack, moves the 
current line pointer to point to the null line added above the 
marker, and deletes that line, the marker, and the null line that 
was inserted following the marker. The RESTORE subcommand restores 
editor settings. 

13 This edit macro is self-documenting. If $DOUBLE is invoked with a 
question mark, or invoked with an argument, information regarding 
its proper use is displayed. 
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User-Written Edit Macros 

You can create the edit macros shown below, for your own use in CMS. 
You may want to refer to them as examples when you are learning to write 
your own macros. The macros have not been formally tested by IBH; they 
are presented for your convenience only. 



SMACROS 

The $MACROS edit macro verifies the existence of and describes the usage 
of edit macros. If you enter: 

$macros 

it lists the filenames of all the edit macros on your accessed disks. 
If you enter: 

$macros namel name2 

it displays, for each valid macro name entered, the macro format and 
usage. (This macro assumes that all macros have been designed to 
respond to a ? request.) The format of the SMACROS edit macro 
instruction is: 



I ^ 1 

I SHACROS I [filenamel [filename2 [ f ilenamen] ] ] i 

I I 



filename is the filename (s) of macro files whose usage is to be 
displayed. If filename is omitted, the filenames of all 
available macro files are listed. 

To create $MACROS, enter: 

edit $fflacros exec 

and in input mode, enter the following: 



i 
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SCONTROL OFF 

&IF &INDEX EQ 1 &IF Si EQ ? &GOTO -TELL 

&IF &INDEX GT &GOTO -PARTIC 

♦ 

SBEGTYPE ALL 

EXEC FILES STARTING WITH A DOLLAR-SIGN ARE AS FOLLOWS, 

FOR INFORMATION ON ONE OR MORE OF THEM, TYPE: 

$MACROS FILENAME1 <FILENAME2> 

SEND 

LISTF $* EXEC * (NOHEADER FNAME) 

6EXIT 

♦ 

-PARTIC STRIP = 

SINDEX1 = 

* 

SLOOP -ENDLOOP SINDEX 
SINDEXl = SINDEX1 + 1 
SSOB = SSOBSTR SSINDEX1 1 1 
SIF SSOB EQ $ SGOTO -STATIT 

STYPE SSINDEXI IS INVALID 
STRIP = 1 
SGOTO -ENDLOOP 

-STATIT STATE SSINDEX1 EXEC * 
SIF SRETCODE EQ SGOTO -CALLIT 
STYPE 6SINDEX1 NOT FOUND 
STRIP = 1 
SGOTO -ENDLOOP 
-CALLIT EXEC S&INDEX1 ? 
-ENDLOOP 
* 

SEXIT STRIP 
* 

-TELL SBEGTYPE 

»$MACROS« HANDLES THE »$MACROS« REQUEST. 

TYPE 'IMACROS' ALONE FOR MORE INFORMATION. 

SEND 

SEXIT 



$MARK 

The $MARK edit macro inserts from one to six characters, starting with 
the current line and in the column specified, for a specified number of 

I records. If there is data already in the columns specified, it is 

I overlayed. If you enter: 

$mark 

the macro places an asterisk (*) in column 72 of the current line. If 
you enter: 

$mark 10 30 abc 

the macro places the string ABC beginning in column 30 in each of ten 
records, beginning with the current record. The format of the $MAHK 
edit macro instruction is: 

I ' 1 

I I r r r tit I 

I SHARK I I n I col 1 char | i | I 

I 1111221 * I M I 

I I L L L JJJ I 

I . -J 
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where : 

n indicates the number of consecutive lines, starting with the 
record currently being pointed to, that will be narked. If n is 
not specified, 1 is assumed, and the other default values are 
also assumed. 

col indicates the starting column in each record where the character 
string is to be inserted. The default is column 72. 

char indicates from one to six characters to be inserted in each 
record. The default is an asterisk (*) - 

To create $MARK, enter: 

edit $mark exec 

and in input mode, enter the following: 

SCONTROL OFF 

&IF SINDEX EQ 1 SIF S1 EQ ? SGOTO -TELL 

SIF SINDEX GT 3 SGOTO -BADPARM 

6INDEX1 = 1 

SIF SINDEX GT SINDEX1 = Si 

SIF SINDEX1 LT SGOTO -BADPARM 

SINDEX2 = 72 

SIF SINDEX GT 1 SINDEX2 = S2 

SIF SINDEX2 LT SGOTO -BADPARM 

SIF SINDEX2 GT 133 SGOTO -BADPARM 

SCHAR = * 

SIF SINDEX EQ 3 SCHAR = S3 

SLEN3 = SLENGTH SCHAR 

SIF SLEN3 GT 6 SGOTO -BADPARM 

SSTACK LIFO RESTORE 

SSTACK LIFO OVERLAY SCHAR 

SSTACK LIFO REPEAT SINDEX 1 

SSTACK LIFO TABS SINDEX2 

SBEGSTACK LIFO 

IMAGE ON 

TRUNC * 

VERIFY OFF 

LONG 

PRESERVE 

SEND 

SEXIT 

* 

-BADPARM SBEGTYPE 

INVALID $MARK OPERANDS 

SEND 

SEXIT 1 

* 

-TELL SBEGTYPE 

CORRECT FORM IS: $MARK <N <COL <CHAR»> 

POTS A 1-6 CHARACTER STRING IN COLUMN 'COL* OF 'N* LINES, STARTING 

WITH THE CURRENT LINE. THE NEW CURRENT LINE IS THE LAST LINE 

MARKED. DEFAULTS ARE: N=1; C0L=72; CHAR=*. 

SEND 

SEXIT 



i 
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$POINT 

The $POINT edit nacro positions the current line pointer at the 
specified line nunber. The line numbers oust be in coluans 73 through 80 
and padded with zeros. For example, if you enter: 

$point 800 

the current line pointer is positioned at the line that has the serial 
number 00000800 in columns 73 through 80. The format of the SPOINT 
macro instruction is: 

I ' 1 

I SPOINT I key I 

I ^ 1 

where : 

key is a one- to eight-character line number. If the specified key 
is less than eight characters long, it is padded with leading 
zeros. 

To create SPOINT, enter: 

edit Spoint exec 

and in input mode, enter the following: 

&CONTR0L OFF 

&IF SINDEX EQ SGOTO -TELL 

&IF SINDEX EQ 1 SIF &^ EQ ? SGOTO -TELL 

SIF SINDEX GT 1 SGOTO -BADPARM 

SKEYL = SLENGTH Si 

SINDEX1 = 8 - SKEYL 

SZ = SSUBSTB 00000000 1 SINDEX1 

S1 = SCONCAT SZ SI 

SSTACK LIFO RESTORE 

SSTACK LIFO FIND SI 

SBEGSTACK LIFO 

TOP 

TABS 73 

IHAGE ON 

LONG 

PRESERVE 

SEND 

SEXIT 

* 

-BADPARM SBEGTYPE ALL 

INVALID SPOINT OPERANDS 

SEND 

SEXIT 1 

« 

-TELL SBEGTYPE ALL 

CORRECT FORM IS: SPOINT KEY 

IF 'KEY* CONTAINS LESS THAN 8 CHARACTERS, IT IS PADDED WITH LEADING 

ZEROS. THE FILE IS THEN SEARCHED FROM THE TOP FOR 'KEY' IN COLUMNS 

73-80. 

SEND 

SEXIT 
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$COL 

The $COL edit macro inserts, after the current record in the file, a 
line containing column numbers (that is, 1, 6, 11, -.-, 76). The format 
of the $COL macro instruction is: 



I ' 1 

I $COL I I 

I 1 

NO operands are used with $COL. If any arguments are entered, the macro 
usage is explained. 

To create $COL, enter: 

edit $col exec 

and in input mode, enter the following: 

SCONTROL OFF 

8IF 8INDEX NE SGOTO -TELL 

6STACK LIFO RESTORE 

6STACK LIFO 

SBEGSTACK LIFO ALL 

1 6 11 16 21 26 31 36 41 46 51 56 61 66 71 76 

&END 

&STACK LIFO INPUT 

SBEGSTACK LIFO 

TRUNC * 

VERIFY OFF 

LONG 

PRESERVE 

SEND 

&EXIT 

* 

-TELL SBEGTYPE 

CORRECT FORM IS: $COL 

INSERTS A LINE INTO THE FILE SHOWING COLUMN NUMBERS. 

&END 

8EXIT 



i 
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I Part 4. Learning to Use the HELP Facility 



The CHS HELP facility enables the user to interactively display coinand 
and message information on a terminal. The command and message 
information is contained in files either supplied by IBM or created by 
the user. 

"Section 18. HELP File Naming Conventions and Creation** describes the 
naming conventions for HELP facility files and techniques that the HELP 
facility provides for creating user HELP description files. 
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Section 18. HELP File Naming Conventions 
and Creation 



I The HELP facility enables the user to: 

• Extend the command and message description files IBM provides with 
additional description files of the user's choice 

• Produce a formatted terminal display by using the HELP format words 
when creating the HELP description file 

Naming Conventions 

When you extend the HELP text files IBM provides, you must use the 
following naming conventions for the HELP files: 

• The filename for components, commands, subcommands, or EXECs must be 
the exact full name of the component, command, subcommand, or EXEC. 

• The filename for messages has the form xxxnnnt where: 

XXX is the component code prefix (for example, DMS for CMS 
messages) . See VM/370 System Messages for a list of the 
component code prefixes. 

nnn is the message number. 

t is the message type code (for example, E for error messages in 
CMS) . 

For example, the filename for the CMS message "NO FILEMAME SPECIFIED" 
would be DMS001E. 

• The filetype for components, commands, or EXECs is *HELPxxxx* where 
xxxx identifies the system associated with this component, command, 
or EXEC. For example, the filetype for a CMS command would be 
•HELPCMS*. 

• The filetype for subcommands is •HELPxxxx' where xxxx identifies the 
command name associated with this subcommand; for example, DEBD for 
the DEBUG command. 

• The filetype for messages is *HELPMSG«. 

• The filetype for a list of all supported commands for a given 
function is •HELPMENU*. 

The following examples illustrate the naming conventions required to 
interface with the HELP command. 

description 

A CMS command description 
A CMS command description 
An EDIT subcommand description 
A CMS message description 

A list of the CMS command and/or EXEC names 
supported by the HELP facility 



Filename 


Filetype 


ACCESS 


HELPCMS 


EDIT 


HELPCMS 


CHANGE 


HELPEDIT 


DMS186W 


HELPMSG 


CMS 


HELPMENO 
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I HELP File Creation 

Osers creating additional files for the HELP facility can format their 
own file or use the format words the HELP facility supports. These 
format words do the following: 

Draw boxes to enclose tables, illustrations or text 

Place comments within a file 

Indicate that certain input lines are to be included in the formatted 
output only under certain conditions 

Cause concatenation of input lines and left- and right- justification 
of output 

Indent only the next input line the specified number of spaces 

Indent a series of input lines the specified number of spaces 

Indent the specified number of spaces all but the first line in a 
series of input lines 

Insert blank lines between output lines 

Change the final output representation of any input character 

The HELP format words are summarized in Figure 23.1. Descriptions 
and examples of their use follow. 
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Format Word 



.BX (BOX) 



CM 
(COMMENT) 

, CS 
(CONDI- 
TIONAL 
SECTION) 

, FO 
(FORMAT 
-MODE) 



.IL (IN- 
DENT LINES) 



IN (IN- 
DENT) 



OF (OFF- 
SET) 



-SP 



(SPACE) 



.TR (TRANS- 
LATE) 



operand Format 



VI V2 ...Vn 
OFF 



Comments 



n ON/OFF 



ON/OFF 



n| +n |- n 



n| +n |- n 



n| + n|- n 



s t 



Function 



Draws horizontal and 
vertical lines around 
subsequent output text, 
in blank columns. 

Places comments in a file 
for future reference. 

Allows conditional 
inclusion of input in 
the formatted output. 



Causes concatenation of 
input lines, and left and 
right justification of 
output. 

Indents only the next 
line the specified 
number of spaces. 

Specifies the number 
of spaces subsequent 
text is to be indented. 

Provides a technique 

for indenting all but the 

first line of a section - 

specifies the number of 
blank lines to be inserted 
before the next output line. 

Specifies the final output 
representation of any input 
character. 



Break 



Yes 



No 



No 



Yes 



Yes 



Yes 



Yes 



Yes 



No 



Default Value 



Draws a 

horizontal 

line- 



On 



I Figure 23.1. HELP Format Word Summary 
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I ENCLOSING TEXT (.BX FORMAT WORD) 

The HELP facility can insert vertical and horizontal lines in the 
foriatted output to enclose text, illustrations, or tables. You use the 
-BX format ¥ord to specify when you want the horizontal lines to appear 
and in which columns the vertical lines should appear. 

The .BX format word is used in three steps to completely enclose 
text: 

1. The first time you issue the .BX format word, specify the columns 
in which you want the vertical lines to appear. For example: 

.bx 1 10 20 30 

results in the following output: 

I 1 1 1 



Note that this first occurrence of the .EX format word causes a 
horizontal line to appear between the first and last column you 
specified. 

2. After the first issuance of .BX, begin entering the text that is to 
be enclosed. As HELP formats these lines, vertical lines are 
placed in the columns that you specified on .BX. However, if a 
column already has a data character in it, it is not overlaid with 
the vertical line. 

Note that whenever you want just a horizontal line to appear (for 
example, to separate lines in a table) , enter the .BX format worX 
without operands. For example: 

.bx 

results in the following output: 

I .( 1 1 



3. When you have finished entering the text that is to be enclosed, 
issue: 

.bx off 

to cause another horizontal line to appear and to prevent any more 

vertical lines from appearing. This output is: 






The following example illustrates this technique of enclosing text. 

.fo off 

.bx 1 10 50 

.in 2 

.of 8 

Item 1 Put Itemi text here. 

The second line can be written here. 

.bx 

.of 8 

Item 2 Then put Item2 text here. 

.bx off 
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I When these input lines are processed, the result is: 

I ,. , , 

I I Item1 I Put Itenl text here. I 

II I The second line can be written here. | 
I , -_ 1 1 

I I Item2 IThen put Itea2 text here. | 

I I 1 1 

I This example shows how you can change the vertical structure several 
I times in succession. The control words: 



1 .bx 


10 


20 






1 -sp 
i .bx 


5 ; 


25 






1 -sp 
1 .bx 


10 


20 






1 -sp 
1 .bx 


5 


25 






1 -sp 
1 .bx 


10 


20 






1 -sp 
1 .bx 


off 






1 resi 


lit 


in: 








1 

1 


1 








1 
1 


1 
4 






r~ " 
1 






1 

1 




1 

1 






1 
J 






1 
t 


■1 
1 






r~' 
1 






1 




1 






1 
J 






1 


1 








L 


1 
1 





I PLACING COMMENTS IN HELP FILES (.CM FORMAT HORL) 

I In addition to text and format words, HELP files can contain comments. 

I Comments are useful for: 

I • Tracking files. You can include comments that give your name, the 
I date and reason you created a file, and a future date at which the 
I file may be erased. 

I • Documenting formats. If you use a special format in a HELP file that 
I may be accessed by other people, you may want to place notes within 
I the file explaining how to update the file. 

I • Place-holders. If a file is incomplete, you may want to put comments 
I in the file where information should be added later. 

I You can place comments in a HELP file with the .CM format word: 

I .cm Created 12/21/75 
I .cm Updated 3/3/76 

I HELP ignores all .CM format words when processing. 
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I CONDITIONAL DISPLAY OF TEXT (-CS FORMAT WORD) 

I You can indicate to HELP that certain sections of the file are to be 

I displayed as output only if the appropriate HELP command options are 

I specified. These options are PARM, FORM, DESC, and ALL. (See VM/370 

I CMS Command and Macro Reference for information on the use of these 

I options.)" 

I In order for HELP command processing to display the appropriate 

I information, you must use the .CS format word in the following manner: 

I .CS 1 on 

I (text for DESC option) 

I .CS 1 off 

I .CS 2 on 

I (text for FORM option) 

I .CS 2 off 

j .CS 3 on 

I (text for PARM option) 

I .CS 3 off 



I DSE OF FORMAT MODE (.FO FORMAT WORD) 

I Format-mode processing means that the HELP facility displays the output 

I lines without breaks, unless specifically requested, and 

I right- justified. You may not want this type of formatting in all cases; 

I you may want certain output to appear exactly as it appears in the HELP 

I file. For this, use the .FO format word to turn off format-mode 

I processing as follows: 

I .fo off 

I When you want to resume format-mode processing, enter: 

I .fo on 

I Format-mode processing is the default. 



I INDENTING TEXT (.IN AND .IL FORMAT WORDS) 

I When you are creating documents, you may want to set off paragraphs or 

I portions of text by indenting them. This often improves the readability 

i by emphasizing certain text. You can cause paragraphs to be indented 

I using the .IN format word. For example, the lines: 

I This line is not indented. 

I .in 5 

I This line is indented. 

I result in: 

I This line is not indented. 
I This line is indented. 

I The .IN format word causes a break so that text accumulated before 

I the .IN format word is processed and displayed, then the next text is 

I processed. 
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The .IN format word effectively sets a new left margin for output 
text so that when you want text indented you do not have to enter blanks 
in front of the input lines (as you would for normal typing). HELP 
continues to concatenate and justify input text lines that begin to 
column 1, but displays the output indented the number of spaces you 
specify. 

Here*s another example: 

These few lines of text 

are formatted 

with enough words 

.in 5 

so that you can 

see how HELP'S formatting 

process 

.in +3 

continues and may 

.in -6 

even be reversed, by using a 

negative value. 

These lines may result in: 

These few lines of 
text are formatted 
with enough words 

so that you can 
see how HELP'S 
formatting 
process 

continues and 
may 
even be reversed, 
by using a negative 
value. 

In this example, the first .IN format word shifts output to the right 
five spaces so that text begins in column 6. The second .IN format word 
requests that the current indentation increase by three spaces so the 
left margin is now in column 9. When you supply a negative value with 
the .IN format word, the margin is shifted to the left. 

To cancel an indentation that is in effect, you can use a negative 
value, or you can use the format word: 

-in 

Because is the default value, you need not specify it when you want to 
restore the left margin to column 1. You can specify simply: 

.in 

When you want to indent only a single line of text (that is, the next 
output line), use the .IL format word. For example: 

This line begins in column 1. 

. in 5 

This line begins in column 6, 

which is now the left margin. 

.il -3 

This line is shifted 3 spaces 

to the left of the current margin. 
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-il 3 

This line is shifted 3 spaces to 

the right of the current margin. 

Help processes these lines as follows: 

This line begins in column 1. 
This line begins in 
column 6, which is now 
the left margin. 
This line is shifted 3 
spaces to the left of 
the current margin. 

This line is shifted 
3 spaces to the right 
of the current margin. 

Because the .IL format word causes a break in text, you may find it 
useful to indicate the beginning of a new paragraph. For example: 

.il 3 

This line begins a paragraph. 

.il 3 

This line begins another. 

These lines result in: 

This line begins 
a paragraph. 

This line begins 
another. 



USE OF OFFSETS (.OF FORMAT WORD) 

In HELP formatting, an offset differs from an indentation in that 
offsets do not affect the first line immediately following the format 
word; the second and subsequent input lines are indented the specified 
number of characters. This is useful, for example, when formatting 
numbered lists where text is blocked to the right of the number. 

Hhen a .OF format word is processed, the next text line is printed at 
the current left margin and subsequent lines (until the next .OF or .IN 
format word) are offset the specified number of characters. For 
example, the lines: 

.of 5 

This line begins 

a 5-character offset, 
.of 5 

This is another line offset 

5 characters. 

.sp 

.in 5 

An indent changes the left 

margin and cancels the offset. 

.of 3 

This paragraph begins 

at the new left margin. 

-of 3 

Here*s one more line. 
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I result in: 



This line begins a 

5-character offset. 
This is another line 

offset 5 characters. 

An indent changes 
the left nargin and 
cancels the offset. 
This paragraph 

begins at the new 

left nargin. 
Here's one more 

line. 

An offset can be canceled with the format word. 

.of 

This format word causes a break; subsequent text is printed at the 
current left margin, that is, whatever the indention is (0, if no .IN 
format word is in effect) . 

Any INDENT format word cancels a current offset and resets the left 
margin. If you specify a positive or negative increment with the INDENT 
format word and an offset is in effect, the offset is canceled and the 
new left margin is computed from the current indent value. 

The .IL (INDENT-LINE) format word uses the current margin (the indent 
value plus the offset value) when computing the margin for the next 
line. 

To achieve a format that has several levels of offsetting, you can 
combine the .IN and .OF format words. 

When you use blank space following the item indicator (for example, 
the number in a numbered list) , HELP may add extra blanks when it 
justifies the line; if so, the first line may not be aligned with the 
remainder of the offset item. 



SPACING BETWEEN LINES OF TEXT (.SP FORMAT WORD) 

If you do not want an input line to be concatenated with the line above 
it, you must cause a break. To cause a break in a HELP file, begin a 
line with one or more blank characters (by using the space bar on your 
terminal keyboard) . When HELP reads an input line that begins with a 
blank character, the formatting process is interrupted; all of the text 
that has accumulated for the current line is displayed as is, even if 
more words would have fit on the line; the next input line begins a new 
output line. 

To create paragraphs in text, then, all you have to do is to enter 
spaces at the beginning of each line that is to begin a new paragraph. 
For example, the input lines: 

The quick brown 

fox 

came over to greet the lazy poodle. 

But the poodle was frightened 
and ran away. 
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I may be displayed by HELP as: 

The quick brown fox 
came over to greet the 
lazy poodle. 

But the poodle was 
frightened and ran 
away- 

If you want to place blank lines between lines of text, you can press 
the space bar at least once on a line that has no other text, then press 
the Return or Enter key. 

Instead of entering a blank line, you can use the -SP format word. 
Thus the input lines: 

The quick brown fox came over to 

greet the lazy poodle. 

-sp 

But the poodle was frightened 

and ran away. 

are formatted as follows by HELP: 

The quick brown fox 
came over to greet the 
lazy poodle. 

But the poodle was 
frightened and ran 
away. 

The .SP format word allows you to enter a numeric parameter 
indicating how many spaces you want to leave on the text output. For 
example: 

.sp 5 

indicates that you want to leave five lines of space in the text output. 
You can use multiple spaces when you want a heading or a title to stand 
out, for example the lines: 

A Love Story 

.sp 3 

The quick brown fox 

was eager 

to meet the pretty poodle. 

will result in: 

A Love Story 



The quick brown fox 
was eager to meet the 
pretty poodle. 
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I TRANSLATING OUTPUT CHARACTERS (.TR FORMAT WORD) 

I After HELP has formatted an output line but before it displays that 

I line, HELP may translate any of the characters in that line to a 

I different character representation- You use the .TR format word to 

I request that this translation be done- For example, to request that all 

I blanks (x«40') in the file be displayed as question marks, enter: 

I -tr 40 ? 

I To stop the translation of the question mark as a blank, enter: 

I -tr ? ? 

I Note that when the . TR format word is used without operands, the 

I translation of all characters is stopped - 
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This publication contains the following appendixes: 

A. Summary of CHS Commands 

B. Summary of CP Commands 

C. Considerations for 3270 Display Terminal Users 

D. Sample Terminal Sessions 
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Appendix A: Summary of CMS Commands 



Figures 24 and 25 contain alphabetical lists of the CHS connands and the 
functions perforned by each. Figure 24 lists those commands that are 
available for general use; Figure 25 lists the commands used by system 
programmers and system support personnel who are responsible for 
generating, maintaining, and updating VM/370- Unless otherwise noted, 
CMS commands are described in VM^320 CMS Command and Macro Heference. 

^^de Meaning 

DOS PP Indicates that this command invokes a DOS Program Product, 
available from IBM for a license fee. 

EHEP Indicates that this command is described in VH/370 PL T SEP and 
ISIQS ES^ording Guide. Further detailis on the operands used 
by this command are contained in OS^VS Environmental Recording 
IJiiiM 5J3^ ££i:£ting (EREP) Program. '" 

IPCS Indicates that this command is a part of the Interactive 
Problem Control System (IPCS) and is described in YM/370 IPCS 
nserj,s Guide. 

Op Gd Indicates that this command is described in the VM/370 
Operator's Guide. 

OS PP Indicates that this command invokes an OS program product, 
available from IBM for a license fee. 

SCRIPT Indicates that this command invokes a text processor that is 
an IBM Installed User Program, available from IBM for a 
license fee. 

SPG Indicates that this command is described in the VM/370 System 
Programmer's Guide. "" 

SYSGEN Indicates that this command is described in the VM/370 
Ilannin^ and System Generation Guide. 

In addition to the commands listed in Figure 24 and 25, there are 
seven commands called Immediate commands that are handled in a different 
manner from the others. They may be entered while another command is 
executing by pressing the Attention key (or its equivalent) and are 
executed immediately. The Immediate commands are: 



• HB 


- 


Halt 


batch execution 


• HO 

• HT 

• HX 


- 


Halt 
Halt 
Halt 


tracing 

typing 

execution 


• RO 

• RT 

• SO 


- 


Resume tracing 
Resume typing 
Suspend tracing 
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Con nan d 


1 Code 


1 Osage | 


ACCESS 




1 Identify direct access space to a CMS virtual | 
1 nachine, create extensions and relate the disk | 
I space to a logical directory. j 


AHSERV 




1 Invoke access nethod services utility functions to | 
I create, alter, list, copy, delete, impprt, or | 
t export VSAM cjatalogs and data sets. j 


ASSEMBLE 




lAssemble assenbler language source code. | 


ASS6N 




[Assign or unassign a CMS/DOS system or progranmer | 
logical unit for a virtual I/O device. j 


CMS BATCH 




Invoke the CMS batch facility. | 


COBOL 


OS PP 


Compile OS ANS Version 4 or OS/VS COBOL source | 
cade- 1 


COMPARE 




Compare records in CMS disk files. | 


CONVERT 


OS PP 


Convert free form FORTRAN statements to fixed form. | 


COPYFILE 




Copy CMS disk files according to specifications. | 


CP 




Enter CP coimands from the CMS environment. | 


CPEREP 


EREP 


Formats and edits system error records for output. | 


DDR 




Perform backup, restpre, and copy operations for | 
disks. 1 


DE30G 




Enter DEBUG subcommand environment, debug node. | 


DISK 




Perform disk-to-card and card— to-disk operations | 
for CMS files. I 


DLBL 




Define a DOS filename or VSAM ddname and relate | 
that name to a disk file. j 


DOSLIB 




Delete, compact, or list information about the | 
phases of a CMS/DOS phase library. | 


DOSLKED 




Link-edit CMS text decks or object modules from a | 
poS/VS relocatable library and place then in j 
executable form in a CMS/DOS phase library. | 


DOSPLI 


DOS PP 


Conpile DOS PL/I source code under CMS/DOS. | 


DSERV 




Display information contained in the DOS/VSE core | 
image, relocatable, source, procedure, and j 
transient directories. | 
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iCoimand 


(Code 


1 Usage ( 


lEDIT 




llnvoke the CMS editor to create or lodify a disk ( 
t file. ( 


(ERASE 




1 Delete CMS disk files. ( 


lESERY 




1 Display, punch or print an edited (coapressed) ( 
1 macro from a DOS/VSE source statement library ( 
t (E sublibrary) . j 


lEXEC 




1 Execute special procedures made up of frequently ( 
1 used sequences of commands. j 


iFCOBOL 


DOS PP 


i Compile DOS/VS COBOL source code under CMS/DOS. ( 


(FETCH 




Fetch a CMS/DOS or DOS/VSE executable phase. ( 


(FILEDEF 




Define an OS ddname and relate that ddnane to any j 
1 device supported by CMS- j 


( FORMAT 




Prepare disks in 800-, 102U-, 2048-, or 4096-byte ( 
i block format. ( 


( FORTGI 


OS PP 


Compile FORTRAN source code using the G1 compiler. ( 


(FORTHX 


OS PP 


Compile FORTRAN source code using the H— extended ( 
compiler. ( 


(6ENDIRT 




[Fill in auxiliary module directories. ( 


jGENMOD 




Generate nonreloca table CMS files (MODULE files). ( 


( GLOBAL 




Identify specific CMS libraries to be searched for j 
macros, copy files, missing subroutines, or DOS j 
executable phases. j 


( GOFORT 


OS PP 


Compile FORTRAN source code and execute the program! 
using the FORTRAN Code and Go compiler. j 


( HELP 




Display information regarding CP, CMS, or user— ( 
supplied commands and messages. j 


(INCLUDE 




Bring additional TEXT files into storage and ( 
establish linkages. ( 


(LABELDEF 




Specify standard HDR1 and EOFI tape label descrip— ( 
tion information for CMS, CMS/DOS, and OS ( 
simulation. j 


(LISTDS 




List information about data sets and space ( 
allocation on OS, DOS, and VSAM disks. j 


(LISTFILE 




List information about CMS disk files. ( 


(LIST 10 




Display information concerning CMS/DOS system and ( 
programmer logical units. ( 


(LOAD 




Bring TEXT files into storage for execution. ( 


(LOADMOD 
(MACLIB ( 




Bring a single MODULE file into storage. ( 
Create or modify CHS macro libraries. ( 
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Command 



ICode I 



Usage 



MODMAP I IDisplay the load map of a MODULE file. 

MOVEFILE I I Move data from one device to another device of the 

same or a different type. 

OPTION I IChange the DOS COBOL compiler (FCOBOL) options that 

are in effect for the current terminal session. 

PLIC I OS PP I Compile and execute PL/I source code using the 

PL/I Checkout Compiler. 

PLICR I OS PP I Execute the PL/I object code generated by the OS 

PL/I Checkout Compiler. 

PLIOPT I OS PP (Compile PL/I source code using the OS PL/I 

Optimizing Compiler. 

PRINT I I Spool a specified CMS file to the virtual printer. 

PSERV I I Copy a procedure from the DQS/VSE procedure library 

onto a CMS disk, display the procedure at the 
terminal, or spool the procedure to the virtual 
punch or printer- 

PUNCH I I Spool a copy of a CMS file to the virtual punch. 

QUERY I I Request information about a CMS virtual machine. 

BEADCARD | |Read data from spooled card input device. 

RELEASE I I Make a disk and its directory inaccessible to a CMS 

virtual machine. 

RENAME I IChange the name of a CMS file or files. 

RSERV I I Copy a DOS/VSE relocatable module onto a CMS disk, 

display it at the terminal, or spool a copy to 
the virtual punch or printer. 

RUN I I Initiate series of functions to be performed on a 

source, MODULE, TEXT, or EXEC file. 

SCRIPT I SCRIPT I Format and print documeni:s according to embedded 

SCRIPT control words in the document file. 

SET I I Establish, set, or reset CMS virtual machine 

characteristics- 

Figure 24. CMS Command Summary (Part 3 of 4) 



330 IBM VM/370 CMS User's Guide 



Pg. of GC20- 1819-2 Rev March 30, 1979 by Supp. SD23-902U-1 for 57U8-IX8 



1 

ICoMiand 
1 


ICode 


1 Usage j 


ISORT 

1 
1 






1 Arrange a specified file in ascending order j 
1 according to sort fields in the data records. j 


ISSERV 
1 

1 
1 






ICopy a DOS/VSE source statement book onto a CHS | 

1 disk, display it at the terminal, or spool a copy j 

to the virtual punch or printer. | 


1 START 

1 
1 






Begin execution of programs previously loaded (OS j 
1 and CMS) or fetched (CMS/DOS) . | 


1 STATE 
I 






?erify the existence of a CMS disk file. | 


ISTATEi 
1 






Yerify a file on a read/write CHS disk. 1 


1 

ISVCTRACE 
1 






Record information about supervisor calls. | 


1 

ISYHONYM 

1 
1 






Invoke a table containing synonyms you have created! 
for CMS and user-written commands- j 


1 

ITAPE 

1 

1 
1 






Perform tape— to— disk and disk-to-tape operations | 
for CMS files, position tapes, and display or j 
write V0L1 labels. j 


ITAPEMAC 

1 
1 






Create CMS MACLIB libraries directly from an j 
lEHMOVE-created partitioned data set on tape. j 


ITAPPDS 

1 
1 






Load OS partitioned data set (PDS) files or card j 
image files from tape to disk. | 


ITESTCOB 
1 


OS 


PP 


Invoke the OS COBOL Interactive Debug Program. j 


ITESTFORT 
1 


OS 


PP 


Invoke the FORTRAN Interactive Debug Program. | 


1 

ITXTLIB 
1 






Generate and modify text libraries. | 


1 

ITYPE 
1 






Display all or part of a CMS file at the terminal. 1 


{UPDATE 

1 1 
1 






Make changes in a program source file as defined j 
by control cards in a control file. | 


I7SAPL 

1 1 


OS 


PP 


Invoke VS APL interface in CMS. | 


1 1 
IVSBASIC 1 

1 1 


OS 


PP 1 


Compile and execute VS BASIC programs under CHS. j 


1 1 
IVSBOTIL 1 


OS 


PP 


Convert BASIC 1.2 data files to VS BASIC format. | 



Figure 24. CHS Command Summary (Part 4 of 4) 
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r' 

1 Command 


Code 


Usage 


IASM3705 1 


SYSGEN 


Assemble 370x source code. 


jflSMGEND 


SYSGEN 


Regenerate the VM/370 assembler command modules. 


IGMSGEND 


SYSGEN 


Generate a new CMS disk— resident module from 
updated TEXT files. 


ICMSXGEN 


SYSGEN 


Generate the CMSSEG discontiguous saved segment. 


ICPEREP 


EREP 


Formats and edits system error records for output. 


ICIRECT 


Op Gd 


Set up VM/370 directory entries. 


IDOSGEN 


SYSGEN 


Load and save the CMSDOS shared segment. 


IDUMPSCAN 


IPCS 


Provide interactive analysis of CP abend dumps. 


IGEN3705 


SYSGEN 


Generate an EXEC file that assembles and link— edits 
the 370x control program. 


(GENERATE 


SYSGEN 


update VM/370 or the VM/370 directory, or generate 
a new standalone copy of a service program. 


ILKED 


SYSGEN 


Link-edit the 370x control program. 


INCPDDMP 


OP Gd, 


Process CP spool reader files created by 370x 




SPG 


dumping operations. 


|PRB 


IPCS 


update IPCS problem status. 


IPROB 


IPCS 


Enter a problem report in IPCS. 


ISAVENCP 


SYSGEN, 


Read 370x control program load into virtual 




SPG 


storage and save an image on a CP-owned disk. 


1 SETKEY 


SPG 


Assign storage protect keys to iStorage assigned to 
named systems. 


ISTAT 


IPCS 


Display the status of reported system problems. 


IVMFBLD 


SYSGEN 


Generate and/or update VM/370 using the PLC tape. 


IVMFDOS 


SYSGEN 


Create CMS files for DOS modules from DOS library 
distribution tape or SYSIN tape. 


IVMFDOMP 


op Gd, 


Format and print system abend dumps; under IPCS, 




IPCS 


create a problem report. 


IVMFLOAD 


SYSGEN 


Generate a new CP, CMS or RSCS module. 


IVSAMPP 


SYSGEN 


Load and save the CMSVSAM, CMSAMS, and CMSBAM 
segments. 


IZAP 


[Op Gd, 
ISPG 


1 Modify or dump LOADLIB, TXTLIB, or MODULE files. 



Figure 25. CMS Commands for System Programmers 
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Figure 26 describes the CP command privilege classes. 



Class 



A* 



B* 



Ci 



Di 



El 



Fi 



G2 



Any = 



H 



User and Function 



ZLiE^El Sxste 
Vm7370 system 
system consol 
responsible f 
communication 
user controls 
machine perfo 
affect the ov 



1 Q£§£ator: The class A user controls the 
. Class A is assigned to the user at the VM/370 
e during IPL. The primary system operator is 
or the availability of the VM/370 system and its 
lines and resources. In addition, the class A 
system accounting, broadcast messages, virtual 
rmance options and other command operands that 
erall performance of VM/370. 



Note: The class A system operator who is automatically logged 
on during CP initialization is designated as the primary 
system operator. 

Sistem Resource Operator: The class B user controls all the 
real resources of the VM/370 system, except those controlled 
by the primary system operator and spooling operator. 

Sistem Programmer: The class C user updates certain 
functions of the VM/370 system- 

S£Ooling Operator: The class D user controls spool data 
files and specific functions of the system's unit record 
equipment. 

System Anal;yst: The class E user examines and saves certain 
data in the VM/370 storage area. 

Service Representative: The class F user obtains, and 
examines, in detail, certain data about input and output 
devices connected to the VM/370 system. 

general User: The class G user controls functions associated 
with the execution of his virtual machine. 

The Any classification is given to certain CP commands that 
are available to any user. These are primarily for the 
purpose of gaining and relinquishing access to the VM/370 
system. 

Reserved for IBM use. 



1 Described in the VM/370 Q£eratorJI_s Guide. 

2Described in the VM/370 CP Command Reference for General Users. 

I 2 ,Z- -...Z " " , ., . 

Figure 26. CP Privilege Class Descriptions 
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Figure 27 contains an alphabetical list of the CP conmands, the 
privilege classes which may execute the command, and a brief statement 
about the use of each command. 



i Command 


Privilege 1 
Class 1 


1 * 


any | 


i *CP 


any | 


1 ACNT 


A 1 


1 ADSTOP 


G 1 


1 ATTACH 


B t 
B 1 
B i 


1 ATTN 


G 1 


1 AOTOLOG 


A,B 1 


1 BACKSPAC 


D 1 


1 BEGIN 


G i 


1 CHANGE 


D,G 1 


1 CLOSE 


G 1 


1 COUPLE 


G 1 


1 CP 


any | 


1 DCP 


C,E 1 


1 DEFINE 


G 1 
B 1 



Usage 



Annotate the console sheet. 

Execute a CP command while remaining in the 
virtual machine environment. 

Create accountii^g records for logged on users, 
reset accounting data, and close the spool 
file that is accumulating accounting records. 

Halt execution at a specific virtual machine 
instruction address. 

Attach a real device to a virtual machine. 
Attach a DASD device for CP control. 
Dedicate all devices on a particular channel 
to a virtual machine. 

Make an attention interruption pending for the 
virtual machine console. 

Automatically log on a virtual machine and 
have it operate in disconnect mode. 

Restart or reposition the output of a unit 
record spooling device. 

Continue or resume execution of the virtual 
machine at either a specific storage location 
or at the address in the current PSW. 

Alter one or more attributes of a closed spool 
file. 

Terminate spooling operations on a virtual card 
reader, punch, printer, or console. 

Connect channel—to— channel adapters. 

Execute a CP command while remaining in the CMS 
virtual machine environment. 

Display real storage at terminal. 

Reconfigure your virtual machine. 
Redefine the usage of SYSVIRT and VIRTUAL 3330V 
devices. 



Figure 27. CP Command Summary (Part 1 of 4) 
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Command 


Privilege 
Class 


DETACH 


B 
B 
B 
G 
G 


DIAL 


any 


DISABLE 


A,B 


DISCONN 


any 


DISPLAY 


G 


DMCP 


C,E 



DRAIN 
DUMP 

ECHO 

ENABLE 
EXTERNAL 

FLUSH 

FORCE 

FREE 

HALT 

HOLD 

INDICATE 
IPL 
LINK 

LOADBUF 



A,B 
G 



A 
D 
A 

D 

A,E,G 
G 
G 



Usage 



Disconnect a real device from a virtual machine. 

Detach a DASD device from CP. 

Detach a channel from a specific user. 

Detach a virtual device from a virtual machine. 

Detach a channel from your virtual machine. 

Connect a terminal or display device to the 
virtual machine's virtual communication line. 

Disable 2701/2702/2703, 370X in EP mode, 
and 3270 local communication lines. 

Disconnect your terminal from your virtual 
machine. 

Display virtual storage on your terminal. 

Dump the specified real storage location on your 
virtual printer. 

Halt operations of specified spool devices upon 
completion of current operation. 

Print the following on the virtual printer: 

virtual PSW, general registers, floating— point 
registers, storage keys, and contents of 
specified virtual storage locations. 

Test terminal hardware by redisplaying data 
entered at the terminal. 

Enable communication lines. 

Simulate an external interruption for a virtual 
machine and return control to that machine. 

Cancel the current file being printed or punched 
on a specific real unit record device. 

Cause logoff of a specific user. 

Remove spool HOLD status. 

Terminate the active channel program on 
specified real device. 

Defer real spooled output of a particular user. 

Indicate resource utilization and contention. 

Simulate IPL for a virtual machine. 

Provide access to a specific DASD by a 
virtual machine. 

Load real UCS/OCSB or FCB printer buffers. 



Figure 27. CP Command Summary (Part 2 of 4) 
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Command 


Privilege 
Class 


LOADVFCB 


G 


LOCATE 


C,E 


LOCK 


A 


LOGOFF 


any 


LOGON 


any 


MESSAGE 


A,B,any 


MONITOR 


A,E 


MSGNOH 


B 



NETWORK 



NOTREADY 



ORDER 



PURGE 


D,G 


QDERY 


A,B,C,D, 
E,F,G 


READY 


G 


REPEAT 


D 


REQUEST 


G 



RESET 



REWIND 



SAVESYS 



SET 



A,B,F 



D,G 



A,B,E,F, 
G 



Usage 



Load virtual forms control buffer for a virtual 
3203 or 3211 printer. 

Find CP control blocks. 

Bring virtual pages into real storage and lock 
them; thus, excluding them from future paging. 

Disable access to CP. 

Provide access to CP. 

Transmit messages to other users. 

Trace events of the real machine and record 
system performance data. 

Send a specified message, without the standard 
message header, from one virtual machine to 
another. 

Load, dump, trace, and control the operation of 
the 370X control program. Control the 
operation of 3270 remote devices. 

Simulate "not ready" for a device to a virtual 
machine. 

Rearrange closed spool files in a specific 
order. 

Remove closed spool file from system. 

Request information about machine configuration 
and system status. 

Simulate device end interruption for a virtual 
device - 

Repeat (a specified number of times) printing or 
punching of a specific real spool output file. 

Make an attention interruption pending for the 
virtual machine console. 

Clear and reset all pending interruptions for a 
specified virtual device and reset all error 
conditions. 

Rewind (to load point) a tape and ready a tape 
unit. 

Save virtual machine storage contents, 
registers, and PSW. 

Operator — establish system parameters. 
User — control various functions within the 
virtual machine. 



Figure 27. CP Command Summary (Part 3 of 4) 
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r-- 

1 Command 


Privilege 
Class 


Usage 


1 SHUTDOWN 


A 


Terminate all VM/370 functions and checkpoint CE 
system for warm start. 


1 SLEEP 


any 


Place virtual machine in dormant state. 


1 SMSG 


G 


Send special message to appropriate virtual 
machine. 


1 SPACE 


D 


Force single spacing on printer. 


1 SPOOL 


G 


Alter spooling control options; direct a file to 
another virtual machine or to a remote 
location via the RSCS virtual machine. 


1 SPTAPE 


D 


Dump output spool files on tape or load output 
spool files from tape. 


I START 


D 


Start spooling device after draining or changing 
output classes. 


1 STCP 


C 


Change the contents of real storage. 


1 STORE 


G 


Alter specified virtual storage locations and 
registers. 


1 SYSTEM 


G 


Simulate RESET, CLEAR STORAGE, and RESTART 
buttons on a real system console. 


1 TAG 


G 


Specify variable information to be associated 
with a spool file or output unit record 
device. 

Interrogate the current TAG text setting of a 
given spool file or output unit record device. 


1 TERMINAL 


G 


Define or redefine the input and attention 
handling characteristics of your virtual 
console. 


1 TRACE 


G 


Trace specified virtual machine activity at your 
terminal, spooled printer, or both. 


1 TRANSFER 


D,G 


Transfer input files to or reclaim input files 
from a specified user's virtual card reader. 


1 UNLOCK 


A 


Unlock previously locked page frames. 


1 VARY 


B 


Mark a device unavailable or available. 


1 9ARNING 


A,B 


Transmit a high priority message to a specified 
user or to all users. 



Figure 27. CP Command Summary (Part U of 4) 
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Appendix C: Considerations for 3270 Display 
Terminal Users 



The IBM 3270 display terninal, coiionly referred to as a 3270, functions 
soievhat differently from a typewriter-style terninal when yon nse it as 
a virtual machine console under VII/370. Apart froa the obvious 
difference in the vay output is displayed, there are special techniques 
you can use vith a 3270 that you cannot use on a 27U1 or other 
typewriter teroinal. This appendix describes how. to use a 3270 and 
provides additional notes to supplement discussions in the first part of 
this publication. 

Entering Commands 

Since the keyboard on a 3270 is never locked during the execution of a 
comnand or program, you can enter successive command lines without 
waiting for the completion of the previous command. This stacking 
function can be combined with the other methods of stacking lines, such 
as using the logical line end symbol (#) to stack several command lines. 
If you try to enter more lines than the terminal buffer can accommodate, 
however, you receive the status message NOT ACCEPTED and you must wait 
until the buffer is cleared before you can enter the line. 

You will find, as you become accustomed to using a 3270, that the iCP 
function is very useful. The #CP function, remember, is a function that 
allows you to pass a command line to the control program immediately, 
bypassing any processing by the virtual machine (CHS) . The «CP function 
can be used in any VH/370 environment, and you can enter it even when a 
program is executing. Tou do not have to interrupt a program's execution 
to enter a command line such as: 

#cp display psw 
to display the current PSW, or: 

#cp spool printer class s 
to spool your virtual printer. 

SETTING PHOGRAM FUNCTION KEYS 

If there are CP and CMS commands that you use frequently, you can set 
the program function (PF) keys on your terminal to execute them. Some 
examples of commands you might wish to catalog on PF keys are: 

#CP DISPLAY PSW 

#CP QUERY PRINTER ALL 

QUERY SEARCH 

To set functions keys 1, 2, and 3 to perform these command functions, 
enter: 

cp set pf 1 immed "#cp display psw 

cp set pf2 immed "icp query printer all 

cp set Ff3 immed query search 
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When you want to execute a #CP function with a PF key, or you want a PF 
key to execute a series of commands, you must use the logical escape 
symbol (") when you enter the SET command. For example: 

cp set pf5 immed edit test file"#bo"#input line"#file 
sets the PF5 key as: 

EDIT TEST FILE#BO#INPUT LINE#FILE 

You cannot set lowercase characters in a PF key. 

The above examples use the IMMED operand of the SET command, which 
specifies that the function is performed as soon as you press the PF 
key. You can also set a key so that it is delayed; that is, the command 
or data line is placed in the user input area. Then, you must press the 
Enter key to execute the command. You may modify the line before you 
enter it. This is the default setting (DELAY) for program function keys. 
For example, you might set a key as: 

QDERY DISK Xa 

When you press this PF key, the command line is placed in the user input 
area, with the cursor positioned following the "9" logical character 
delete symbol; you can enter the mode letter of the disk you are 
querying before you press the Enter key to execute the command. If you 
enter 'A', the resulting command as seen by CMS is 'QDERY DISK A*. 

You can set all of your program function keys in your PROFILE EXEC, 
so they are set each time you load CMS. You can change a PF key setting 
any time during a terminal session, according to your needs. If, for 
example, you discover that you are repeating several procedures a number 
of times, and the procedure does not lend itself to being written into 
an EXEC, you could use your program function keys. 

All the lines in an EXEC procedure are scanned, and all character 
strings are truncated to eight characters, so if you enter a long 
command line, insert spaces where possible: 

CP SET PF5 IMMED EDIT TEST FILE #B0# INPUT 

To change PF settings within the edit environment, give the EXEC a 
filename that begins with a dollar sign ($) , so it functions as an edit 
macro. 

For more details on setting PF keys, see the VM/370 Terminal User's 
Guide. 

Controlling the Display Screen 

I During a CP or CMS session (other than an EDIT session) messages and 

I warnings from the system operator or other users are highlighted. This 

I distinguishes these messages from other output and lessens the 

I possibility of important messages being lost or ignored. 

A major feature of a 3270 display screen is the screen status area, 
which indicates, at all times that you are logged on, the current 
operating condition your virtual machine is in. Understanding the 
status conditions can help you use CMS on a 3270 more effectively. The 
screen status area indicates one of six conditions: 
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CP READ: After you log on, this is the first status message you see; it 
indicates that the terminal is waiting for a line to be read by the 
control program. You can enter only CP commands when the screen status 
area indicates a CP READ. 
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VM READ: This status indicates that" your terminal is waiting for a line 

to be issued to your virtual machine; you may be in the CMS environment, 

in the edit or debug environments, or you may be executing a program or 

an EXEC that has issued a read to the console. 

ROHNIHG: This status means that your virtual machine is operating. Once 
you have loaded CMS and are using the CMS environment, this status is 
almost continually in effect, even when you are not currently executing 
a command or program. 

You can alter the way this works by using the AOTOREAD function of 
the SET command- When the AUTOREAD setting is OFF, (the default for 
display terminals) , your terminal displays a RUNNING status after the 
execution of each CMS command. If you want the terminal to be in a VM 
READ status following each command, issue: 

set autoread on 

The ON setting is the default for typewriter terminals, since a read on 
a typewriter terminal must be accompanied by the unlocking of the 
keyboard. 

The advantage of keeping your virtual machine in a running status 
even when it is not actually executing a program is that it makes your 
terminal ready to receive messages. If your terminal is waiting for a 
read, either from CP or from the virtual machine, and if a user or a 
program sends a message to your virtual console, then the message is not 
displayed until you use the Enter key to enter a command or null line. 
When your machine is in a running status, the terminal console is always 
ready to accept messages. 

If your virtual machine is in the CP environment, and you want your 
terminal to be in a running status, you can use the command: 

cp sleep 

To return to the CP READ status, you must press the PA1 key or the Enter 
key. 

MORE.. .; This status indicates that your display screen is full, but 
that there is more data to be displayed. This message, in addition to 
indicating that there is more data, gives you a chance to freeze your 
screen^s current display so you can continue to examine it, if 
necessary. 

When you see the screen is in a MORE... status, you can either (1) 
press the Clear, Cancel, or PA2 keys to clear the screen and see the 
next screen, or (2) press the Enter key to hold the screen in its 
present status. If you do not do either, then after 60 seconds, the 
screen is cleared and the next screen is displayed. 

HOLDING: This indicates that you have pressed the Enter key to freeze 
the screen. You must use the Cancel, Clear, or PA2 keys to erase this 
screen and go on to the next display. 

A holding status also results if you have received a message that 
appeared on this screen. When the screen becomes full, it does not 
automatically pass to the next display after 60 seconds, but waits until 
you specifically clear the screen. (This feature ensures that any 
important messages you receive are not lost.) 

IQl ACCEPTED: Indicates that you are trying to enter a command line but 
the terminal buffer is full and cannot accept it. This message is also 
issued when you attempt to use the 3270 COPY function and a printer is 
either not available or not ready. 
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CONSOLE OUTPUT 

When you use a 3270 terminal as your virtual machine console, you do not 
ordinarily retain a console log, as you do on typewriter terminal. 
There may be many circumstances in which you need a printed record of 
your console output, whether it be to obtain a copy of program-generated 
output, or to retain a record of CP and/or CMS commands that resulted in 
an error condition. There are two techniques you can use in VM/370 to 
obtain hardcopy representations of display terminal sessions: spooling 
console output and the 3270 copy function. 



Spooling Console Output 

The CP SPOOL command provides the CONSOLE operand, which allows you to 
begin and end console spooling. You enter: 

cp spool console start 

when you want to begin recording your terminal session, and: 

cp spool console stop 

when you have finished. In between, you can periodically close the 
console file to release for printing whatever has been spooled thus far: 

cp spool console close 

Other operands that you can enter are the same as you might specify for 
any printer file, such as CLASS, COPY, CONT, and HOLD. 

An alternate technique is to spool your console to your own virtual l^ 
reader: 

cp spool console start * class a 

Then, when you close the console file, instead of being released to the 
CP printer spool file queue, it is routed to your virtual card reader, 
and you can load it onto your A-disk as a CMS disk file: 

readcard console file 

You can then use the editor to examine it (or to delete sections you 
don't need) and use the PRINT command to spool it to the printer. 



3270 COPY Function 

If you are using a 3270 display terminal, and you have available a 3284, 

3286, 3287, 3288, or 3289 printer, you can copy the full screen display 

currently appearing on the screen- To copy the screen, you have to 

assign the copying function to a program function key, with the SET 
command: 

cp set pf9 copy 



Then, whenever you want to copy a screen display, you can press the PF9 
key (or whichever key you set). The display is printed on any 3270 
display printer that is attached to the same remote control unit as the 
display terminal. If, when you press the PF key, the screen status area 
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indicates NOT ACCEPTED, it means that the printer is either not ready or 
not available. When you press the PF key and receive no response, it 
means that the screen has been copied. 

There is a print matrix available to the 3274 and 3276 user that 
allows control of the display to printer operations- In addition, a 
local print key is provided on the 3274 that can be used for copy 
operations. 

Figure 28 is an example of a 3270 screen display that could be copied 
on the printer. When you use the copy function to copy a screen, all 24 
lines of the display screen are copied; the screen status area 
(indicated as RUNNING in Figure 28) is blank if the 3270 is locally 
attached. If the 3270 is remotely attached, the entire screen including 
the screen status area, is copied. You can use the user input area of 
your screen to key in comments, or your name or userid, if several users 
are spooling copy files. 



DEFINE STORAGE 16384K 

STORAGE = 16384K 

IPL 190 

CMS VERSION 3.0 02/28/76 



10:32 



testi ...t. Jones 



RUNNING 



Figure 28. 3270 Screen Display 



Signaling Interruptions 



The two keys on your 3270 keyboard that signal interruptions are the PAl 
key — REQ key on a 3278 Model 2 A — and the Enter key. Throughout this 
publication, interruption signaling has been described in terms of the 
Attention key, which is the interruption signaling key on a 2741. 

On a typewriter terminal, the Attention key, pressed once, causes a 
virtual machine interruption (if the terminal mode is set to VM) ; you 
must use it when you want to enter an Immediate command, such as HT or 
HX. On a display terminal, you can enter these commands whenever your 
virtual machine is in a running status, without having to signal an 
interruption before you enter the command. 

Sometimes, however, if your terminal is displaying output very 
rapidly, you must wait until the screen is full and the screen status 
area indicates a MORE... status before you attempt to enter the HT or HX 
command. 

The Enter key can also be used as an interruption signaling key. If 
you press it once when your virtual machine is running, you will place 
your virtual machine in the VM READ status, so you can enter a command 
line- If you preiSs the Enter key twice, quickly, you enter the CP 
environment, with your console in a CP READ status. 
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An easier way to enter the CP environment is by pressing the PA1 key. 
Whenever you press this key, your virtual machine is placed in a CP HEAD 
status, and you can enter any CP command. From the CP environment, you 
must use the CP command BEGIN to resume execution of your virtual 
machine. 



HALTING SCREEN DISPLAYS 

When your terminal is displaying successive screens of output from a 
program or a CMS command, you can use the HT or HX Immediate commands to 
halt the display or the execution of the command, respectively. If your 
terminal is writing the information e^t a very rapid rate, you may have 
difficulty entering the HT or HX command. In these circumstances, you 
can use the PAl key — REQ key on a 3278 Model 2A — or press the Enter 
key twice to force your terminal to a CP READ status. Then, you can use 
the CP command ATTN or REQUEST to signal a virtual machine read.. When 
the screen status area indicates VM READ, you can enter HX or HT. 

Using the CMS Editor with a 3270 

The CMS editor has a special format and operation, called display mode, 
that makes editing CMS disk files with a 3270 more convenient than on a 
typewriter terminal. It uses most of the display screen, and, depending 
on the terminal type and model, displays, depending upon the terminal 
type end model, up to 38 lines of a file at once. In addition to 
displaying data lines of the file, the editor also indicates, on the 
topmost line of the screen, the filename, filetype, record format, and 
logical record length of the file being edited, as well as showing your 
current mode: input or edit. The format of the screen is shown in 
Figure 29. 

The screen lines that you are most concerned with while editing are 
the current line, the user iiiput area (the bottom two lines) , and the 
editor's message line (the second line from the top) in which the 
editor's responses and error messages are displayed. The current line 
and the editor's message line are highlighted. 

When you first invoke the editor to edit a file, whatever is 
currently on the screen (including your EDIT command line) is erased and 
the full screen is controlled by the editor. The current line pointer 
is positioned at the top of the file, the top part of the display screen 
appears blank. The editor displays the characters "TOF:" and "EOF:" to 
indicate the top and end of the file, respectively. 

ENTERING EDIT SUBCOMMANDS 

When you enter an EDIT subcommand into the user input area and press the 
Enter key the subcommand is not displayed on the screen, but the change 
(or line pointer movement) is reflected in the screen display- If you 
enter a subcommand that moves the current line pointer, all of the lines 
on the screen are shifted up or down, according to the action taken by 
the subcommand. 

If you use the INPUT subcommand to enter input lines, the edit status 
field indicates INPUT; all of the lines that you enter are placed in the 
file and appear on the screen as the current line. (Entering input 
lines from a remote 3270 is somewhat different. The following "Editing 
on a Remote 3270" discusses the differences.) 
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EDIT 1 DISPLAY SCREEN A12 F 80 3 
>»» 1 80 ♦ 



TOF: 5 

THIS IS THE FIRST LINE OF THE FILE. (CURREUT LINE) . ^ 

THIS IS THE SECOND LINE OF THE FILE. 

THIS IS THE THIRD LINE OF THE FILE. 

EOF: 



VM READ 



Notes : 

1 Edit session status. This indicates EDIT, INPUT, or NEW FILE. 
The NEW FILE message appears when you edit a new file; it is 
replaced with INPUT when you enter input mode and thereafter is 
EDIT or INPUT. 

2 The filename, filetype, and filemode of the file. 

3 Record format and logical record length. 

♦ Editor reponse area. The response shown may be the response to 

a VERIFY subcommand entered with no operands, 
s The symbols TOF: and EOF: indicate top of file and end of file, 

respectively. 
6 The current line is located in the approximate center of the 

output area of the screen. 
I 

Figure 29. How the CMS Editor Formats a 3270 Screen 



If you enter an invalid EDIT subcommand, or if you enter a subcommand 
that requests information, the edit response appears in the message 
field of the screen. For example, if you enter: 

trunc 

the editor responds by displaying the current truncation setting, which 
might be: 



>»» 



81 



If you enter: 

copyfile myfile edit (trunc 
the editor would respond: 

>»» ?EDIT: copyfile myfile edit (trunc 

to indicate that it does not recognize the entered line (COPYFILE is not 
an EDIT subcommand) . When you use line-number editing, the prompting 
message appears in this area; after you enter text in the user input 
area, the text line is written in the output display area, at the 
current line position. 
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Two EDIT subcommands, CHANGE and ?, result in lines being copied in 
the user input area- In the case of the CHANGE subcommand, the line that 
is displayed is the current line. Once in the user input area, you can 
modify it and re-enter it. While you are changing it, the original line 
appears unchanged in the output display area. If you decide that you do 
not want changes entered, you must press the Erase Input key and then 
press the Enter key before you enter any other EEIT subcommands. 

You can use the ? subcommand to request that the last EDIT subcommand 
you entered be displayed in the user input area. If, for example, you 
enter a CHANGE or LOCATE subcommand that results in a NOT FOUND 
condition, or some other error, you can enter: 



and modify the subcommand line and re-enter it, if you want; otherwise, 
use the Erase Input key to delete it- 



CONTROLLING THE DISPLAY SCREEN 

Usually the editor controls the entire screen display during an edit 
session. Occasionally, the screen goes into a MORE... status, and you 
must use the Cancel key or PA2 key to clear the screen- There are two 
other situations in which the screen must be cleared, either by the 
editor, or by you. When you use the CMS subcommand to enter CMS subset 
to enter CMS commands, the screen is cleared and the message CMS SUBSET 
is displayed at the top of the screen. When you issue the subcommand 
RETURN to return to edit mode, the screen display is restored to its 
original appearance. 

The situation is slightly different, however, whenever you 
communicate with the control program (CP) , or receive messages from 
other users during an edit session. Any CP message or command response 
causes your screen to go into a MORE... status; you must use the PA2 
(Cancel) key to see the response. To restore your screen to its edit 
display, you should use the EDIT subcommand TYPE. If you use the PAl 
key to place your virtual machine in the CP environment, and the screen 
status area indicates CP READ, use the CP command BEGIN to restore edit 
mode- Then enter the TYPE subcommand. If you enter a subcommand other 
than TYPE, the entire screen is not restored, and the top two lines (the 
editor's data and response fields) may contain lines of the CP response. 

If your virtual machine was in input mode when you entered the CP 
command, you may continue entering lines of input; the third through the 
ninth lines of the screen are restored after you enter the next line- 

If you enter a CP command that does not produce a response, then 
there is no change to the screen. 



Verification Settings on a 3270 

The VERIFY subcommand allows you to alter the verification columns when 
you are editing a file or to cancel verification altogether. If, for 
example, you are editing a file with records longer than 80 characters, 
each line is displayed on two lines of the display screen. Sometimes, 
you may be editing only specific columns in a file, and do not need to 
see the lines displayed in their entirety. To see only the first 80 
columns, you could enter: 
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verify 1 80 



Or, if you wanted to see the last 80 columns of a file with 
120-character records, you could enter: 

verify 41 120 

If you cancel verification entirely by entering: 

verify off 

then modifications that you make to the file (including movement of the 
current line pointer) are not reflected on the display screen until you 
use the TYPE subcommand. 



THE CURRENT LINE POINTER 

There is one aspect of the CMS Editor on a 3270 that is much the same as 
on a typewriter terminal: you must still be concerned with the 
positioning of the current line pointer, and you can only add or modify 
data on the current line, even though you see many lines being 
displayed. The current line, on the screen, appears near the middle of 
the output area of the screen (see Figure 29) . 

To move the current line pointer, you can use the subcommands OP and 
EOWN: UP indicates movement toward the top of the file and DOWN 
indicates movement toward the bottom of the file. When you issue either 
of these subcommands, the entire display of the file shifts down the 
screen (if you use the UP subcommand) or up the screen (if you use the 
DOWN subcommand) . 

If you have never used the CMS editor on a typewriter terminal, you 
may find the UP and DOWN subcommands confusing to use, so you can use 
instead the BACKWARD (UP) and FORWARD or NEXT (DOWN) subcommands to 
shift the display backward (toward the top of the file) and forward 
(toward the bottom of the file) . 

You can also use the EDIT subcommand SCROLL, which allows you to 
display successive screen displays, and to examine an entire file 
quickly. For instance, on a 3270 Model 2 display terminal, you enter 
the SCROLL subcommand with no operands, it is the equivalent of entering 
the subcommand DOWN (FORWARD) 20, which results in the screen changing 
to display the 20 lines following the lines currently being displayed. 
If you enter: 

scroll 10 

The SCROLL subcommand executes 10 times, placing the screen in a MORE... 
state at the end of each display. 

If the file you are editing has verification column settings greater 
than 80 characters (so each line takes up two display lines) , then the 
SCROLL subcommand moves the screen 10 lines at once instead of 20. 

The UP (or BACKWARD) counterpart of SCROLL is SCROLLUP, which can be 
abbreviated SU. 
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USING PROGRAM FUNCTION KEYS 

You can enhance the use of the CMS editor on a 3270 by setting the 
prograa function (PF) keys on your terminal to correspond to some of the 
more frequently used EDIT subcommands, such as DP, DOWN, SCROLL, FILE, 
SAVE, and so on. You can also set a program function key to contain a 
line of data, so that if you are creating a file that has many duplicate 
lines in it, you can use the PF key instead of having to key in the 
entire line each time. PF keys cannot, however, contain lowercase 
character strings. 

YOU can set a program function key while you are in edit mode either 
by using the PA1 key — REQ key on a 3278 Model 2A — to enter the CP 
environment or by using the #CP function. 



USING THE EDITOR IN LINE MODE 

The editor's display mode is the most common format of operation on a 
3270. There are, however, instances when it is not possible or not 
desirable to use the editor in display mode. For these instances, you 
should use the line mode of operation, which is the equivalent to using 
a typewriter terminal. When you use line mode, each EDIT subcommand you 
enter, and the response (if you have verification on) , is displayed, a 
line at a time, on the screen in the output display area. There is no 
full screen display of the file. 

You need only be concerned with using line mode if you are connected 
to VM/370 by a remote 3270 line, or if you are editing a file from 
within an EXEC and you want to control the screen display. Although it 
is possible to use the editor in line mode on a local 3270, it is rarely 
necessary for normal editing purposes. 



Editinc[ on a Remote 3270 

When you invoke the editor from a remote 3270, you are placed in line 
mode by the editor. The advantage of using the 3270 in line mode 
(particularly on a remote editor) is that the editor can respond more 
quickly to display requests. When you use display mode, the editor has 
to write out the entire output display area when you move the current 
line pointer; in line mode, it has only to write a single line. 

If you want to use display mode, you enter the EDIT subcommand: 

format display 

The editor begins operating in display mode, and you can use the special 
editing functions available in display mode. 

However, when you are using a remote 3270 in display mode, and you 
enter the INPUT subcommand to begin entering input lines, the screen is 
cleared, and your input lines are displayed as if you were in line mode, 
beginning at the top of the screen. When you enter a null line to return 
to edit mode, the editor returns to a full screen display. 

You can resume editing in line mode by using the subcommand: 

format line 
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Editing From an EXEC File 

If you invoke the editor from an EXEC, but you do not want the screen 
cleared when the editor gets control, you can specify the NODISP option 
on the EDIT command line: 

edit test file (nodisp 

This places the 3270 in line mode, so that the lines already on the 
screen are not erased. 

The 3270 remains in line mode for the remainder of the edit session, 
and you cannot use the FORMAT subcommand to place it in display mode. 

USING SPECIAL CHARACTERS ON A 3270 

There are two special characters available on a typewriter terminal 
whose functions have no meaning on a display terminal. They are the tab 
character (X'05M and the backspace character (XM6'). For most file 
creation and editing purposes, you will probably not need to use the 
backspace, but many CMS filetypes use tab settings to set up the proper 
column alignment in files. There are two methods you can use to enter 
any special character on a 3270 (including tabs) , and an additional 
method of using tabs, which involves setting a program function key. In 
addition, the tab character can also be set via the CP command TERMINAL 
TABCHAR- 

To enter any special character (a backspace is used in this example) 
you can either: 

1. Enter another character at the appropriate place in the record, and 
then use the ALTER subcommand to alter that character to the 
hexadecimal value of the character you want to represent (a 
backspace character is a XM6*)- For example: 

input ABC»> 
alter > 16 1 * 

When you enter backspaces and overstrike characters on a 3270, 
however, the characters and backspaces each occupy character 
positions, so that a single compound character occupies three 
character positions on the screen. If the image setting is CANON, 
and you want to use the backspace to enter compound characters, you 
must not enter the backspace character first. 

2. Before you begin to create the file, use the CMS SET command to 
define some other character as the backspace character: 

set input > 16 

CMS then translates all occurrences of the character > to X'16»- 

If you need to correct a line that contains backspaces, you can 
reverse the above sequence; alter the X»16* characters to asterisks and 
enter the CHANGE subcommand. 

D^f isisa a 3270 Projgram Function Key for Tab Settings 

You can set up a program function key to operate like a tab key on a 
typewriter terminal. You must use the CP SET command as follows: 

SET PFnn TAB n1 n2 . . . nn 
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where : 

PFnn is any valid function key from PF1 to PF2U. 

n1 n2 . . . nn are the logical tab settings desired, expressed as 
decimal numbers. Invalid tab settings are ignored. You 
can specify the setting values in any order, but they 
are normally specified in ascending order. 

You can define different PF keys with different tab settings for 
different filetypes. Whenever you press the PF key you have set for a 
tab, the cursor moves to the corresponding position in the user input 
area, in much the same way that a typing element on a typewriter would 
move to the next tab stop. 

If you press the PF tab key to a position that already contains a 
data character, the data remains intact. If there is no data in that 
position, a tab character is entered in the file. The effect of the tab 
in the file depends, as in normal usage, on the image setting of the 
editor. If the image setting is set to on (the default) , the tab expands 
to an appropriate number of blanks, to correspond to the settings in 
effect for the TABSET subcommand. When the TAESET settings match the 
tab settings of the PF key, then any lines you enter in the user input 
area appear exactly as they will appear in the output display area. 

If you tab beyond the last defined tab position, the cursor is 
repositioned at the beginning of the user input area. 



Changing ajid Displaying Special Characters 

When you edit a file on a 3270 terminal in display mode, you should not 
copy a line containing tabs or backspaces into the user input area. The 
tabs or backspaces are converted to blanks (X»4G*)- Similarly, if the 
line contains VM/370 logical line editing symbols that have been entered 
as data characters, the symbols are reinterpreted when you enter the 
line. 

If you use the SET OUTPUT function to display nonprintable characters 
in CMS, the character translations do not appear when the editor is in 
display mode. They are, however, displayed when the editor is in line 
mode. 



Using APL with a 3270 

If you have a 3277 or 3278 display station equipped with an APL 
keyboard, you can use APL on a 3270 terminal in CMS. You invoke the APL 
virtual machine by issuing the command specified in the VSAPL Program 
Product documentation. This command invokes the VSAPL-CMS interface 
program. You are then prompted to press the APL On/Off key which is en 
your terminal; pressing this key changes the keyboard to APL character 
input mode. You are then prompted to press the Enter key to continue. 

EBCDIC or APL characters can always be displayed; the APL On/Off key 
does not change this. The VSAPL-CMS interface program issues the 
TERMINAL APL ON command for you and selects the appropriate translation 
tables. The TERMINAL APL ON command automatically forces a TERMINAL 
TEXT OFF condition. The interface program then invokes the VSAPL 
program. When the VSAPL ready message appears on the screen, you can 
use APL. 
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You can send a copy of your display screen to a locally or remotely 
attached printer. Be sure that the printer you send your output to has 
the APL feature installed; if it does not, the APL characters are not 
printed. Most system printers do not have an APL print chain; therefore 
you may need to use the copy function to direct your screen output 
displays to a 3284, 3286, or 3287 printer. 



EBROR SITUATIONS 

If you do not have the APL hardware feature installed on your 3277 or 
3278 but you invoke APL: 

• The VSAPL program is invoked and the TERMINAL APL ON command is 
issued. 

• YOU cannot communicate with the VSAPL program. 

• Any APL characters that are written to the screen appear as blanks. 

If you have the APL feature installed on your terminal, but invoke 
APL manually without issuiiig the TERMINAL APL ON command or issue 
TERMINAL APL OFF at sometime during APL processing: 

• The VSAPL program is activated. 

• You cannot communicate with the VSAPL program. 

• Any APL characters written to the screen appear as blanks. 

If you attempt to use the APL 0/S (overstrike) key when the APL 
hardware key is set off, it acts as a backtab key and repositions the 
cursor to the beginning of the user input area. 



LEAVING THE APL ENVIRONMENT 

Issue the APL command: 

) OFF 
to log off VM/370. 

Issue the APL command: 

) OFF HOLD 

to return to CMS. This APL command invokes the VSAPL-CMS interface 
program, which: 

• Issues the TERMINAL APL OFF command 

• Prompts you to press the APL hardware key 

• Returns to CMS 

Note: The APL hardware feature is a key, not a switch. Each time you 
press the APL key you reverse its on/off setting. To determine whether 
APL is on or off, press a key that represents a special APL character. 
If the character displayed is an APL character, the hardware APL feature 
is set on- If the character displayed is a non-APL character, you must 
press the APL key once to set the APL feature on. 
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Using the 3277 Text Feature 

If you have a 3277 or 3278 display station equipped with the Data 
Analysis Text keyboard, you can key in, as well as display, all of the 
special text characters. For a description of these characters, see the 
YM/370 Terminal Oser^s Guide. 

These characters are in addition to those available with standard EBCDIC 
3270 terminals. If you have a suitably equipped printer attached to 
your 3270, you can use the SET PFnn COPY function to obtain a printed 
copy of the screen. 

When you want to activate the text feature, and use the special 
characters, enter the command: 

cp terminal text on 

The TERMINAL TEXT ON command automatically forces the TERMINAL APL OFF 
command. Now, you can use any of the special characters when you enter, 
change, or locate text lines in a file. 



ERROR SITUATIONS 

If you do not have the appropriate text hardware feature on your 3270, 
but attempt to display a file that contains the characters, the 
characters appear as blanks on a 3277, and as hyphens on a 3276 and a 
3278. 

If you inadvertently issue the TERMINAL TEXT ON command while using a 
terminal that does not have the text capability, you must do the 
following to return to normal operating procedures: 

1. Press the PAl key to enter the CP environment. 

2. Key in, in uppercase letters only, the command line: 

TERMINAL TEXT OFF 



LEAVING THE TEXT ENVIRONMENT 

You leave the special text environment by entering the command: 

cp terminal text off 
Notes 

1. The 3270 text hardware feature is activated by a key, not a switch. 
Each time you press the TEXT On/Off key, you reverse its setting. 
When the red light on the text keyboard is illuminated, the text 
feature is on. 

2. Compound characters, such as a character/backspace/character 
combination, are still entered and displayed as three characters. 
The screen position occupied by the backspace character appears as 
a blank because the character (XM6M is nondisplayable. 
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Appendix D: Sample Terminal Sessions 

This appendix provides saiple teriinal sessions shoving you how to use: 

• The CMS editor (using context editing) , and the CMS COPYFILE, SORT, 
RENAME, and ERASE conmands 

• The CMS editor (using line-number editing) 

• CMS OS simulation to create, assemble, and execute a program using OS 
macros in the CMS environment 

I • CMS DOS/VSE simulation to create, assemble, and execute a program 
I using DOS/VSE macros in the CMS/DOS environment 

• Access method services under CHS, to create VSAM catalogs and data 
spaces, and to use the define and repro functions of AMSER7 
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Sample Terminal Session Using the Editor and CMS 
File System Commands 



This terminal session shows you how to create a CMS f il^ and make changes to it using the 
CMS editor, and then manipulate it using the CMS file system commands, COPYFILE, ERASE, 
RENAME, and SORT. 

Note: Throughout this terminal session whenever a TYPE subcommand or command is issued 
that results in a display of the entire file, the complete display is not shown; omitted 
lines are indicated by vertical ellipses (-..). When you enter the TYPE command or 
subcommand, you should see the entire display- 



edit comma 

NEW FILE: 

EDIT: 

image 

ON 

tabs 1 12 

trunc 72 

input 

INPUT: 

copyfile 

sort 

edit 

edit 

rename 

punch 

print 

erase 

listfile 

state 

statew 

readcard 

disk dump 

TRUNCATED 

DISK DUMP 

disk load 

compare 

tape dump 

tape load 

EDIT: 



nd data 



80 



copy cms files 

sort cms files in alphameric order by specific columns 

create a cms file 

modify a cms file 

change the name of a cms file 

punch a copy of a cms file on cards 

print a cms file 

erase a cms file 

list information on a c 

verify the existence of 

verify the existence of 



file 

cms file 

cms file on a read/write disk 
read a cms file from your card reader onto disk 
punch a cms file in cms disk dump format into your virtual card punch for 

PUNCH A CMS FILE IN CMS DISK DUMP FORMAT INTO YOUR VIRTUAL CA 
read a disk dump file onto disk 
compare the contents of cms disk files 
dump cms files onto tape 
read cms files onto disk from tape 



1 Use the EDIT 
COMMAND and 
the message 

2 Check that 
SCRIPT. Then 
truncation 1 

3 Enter the su 
For these in 
following ea 
in column 12 

H The message 

truncation 1 
you can see 
input mode, 

5 To get out o 
entering any 



command to i 
a filetype of 
NEW FILE. 
the image sett 
, set the log 
imit of 72. 
bcommand INPUT 
put files, you 
ch CMS command 
, the input da 
, TRUNCATED, 
imit you set f 

how much of 
so continue en 
f input mode, 

data) . The e 



nvoke the CMS editor to create a file with a filename of 
DATA. Since the file does not exist, the editor issues 

ing is ON. This is the default for all filetypes except 
ical tab stops for this file at 1, 12, and 80, and set a 

to enter input mode and begin entering lines in the file. 

should press the Tab key (or equivalent) en your terminal 
name. If there is a physical tab step on your terminal 
ta appears aligned. 

indicates that the line you just entered exceeded the 
or the file (column 72) . The editor displays the line, so 
the line was accepted. Your virtual machine is still in 
tering input lines. 

enter a null line (press the Return or Enter key without 
ditor responds with the message EDIT:. 
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6 top 
TOF: 

7 type * 
TOF: 

COPYFILE COPY CMS FILES 



TAPE LOAD READ CMS FILES OHTO DISK FROM TAPE 

8 EOF: 

locate /disk dunp 

DISK DOMP POHCH A CMS FILE IN CMS DISK DUMP FORMAT INTO YOOR VIRTUAL CA 

9 replace disk dump punch a ens file onto cards 
input 

INPUT: 

type display the contents of a ens file at your terminal 

renane alter the name of a ens file 

sort resequence the records in a ens file 

copyfile reformat a file, by colunns 

conprae verify that two files are identical 
10 

EDIT: 

change /rae/are/ 

COMPARE VERIFY THAT TWO FILES ARE IDENTICAL 
11 bo 

TAPE LOAD READ CMS FILES ONTO DISK FROM TAPE 

input 

INPUT: 
12 

EDIT: 
13 file 

R; 



) 



6 Use the TOP subeonmand to position the current line pointer at the top of the file. 
The editor responds TOF:. 

7 Use the TYPE subcommand to display the entire file. Note that all of your input 
lines are translated to uppercase characters, and that the tab characters you 
entered have been expanded, so that the first word following each command name 
begins in column 12. 

8 The nessage EOF: indicates that the end of the file is reached. You can issue the 
LOCATE subcommand to locate a line. Since you are at the bottom of the file, the 
editor begins searching from the top of the file. Notice that you can enter the 
character string you want to locate in lowercase characters; the editor translates 
it to uppercase to locate the line. The editor displays the line. 

9 Use the REPLACE subcommand to replace this line, in a shortened form so that it is 
not truncated. Remember to enter a tab character after the command name; when you 
enter the line, the tab stop does not have to be in column 12. Then, use the INPUT 
subcommand again to resume entering input. The lines that you enter next are written 
into the file following the DISK DUMP line. 

10 When you make a spelling error or other mistake, you may want to correct it 
immediately. Enter a null line to return to edit mode, and use the CHANGE subcommand 
to correct the error. In this example, the string RAE is changed to ARE. The 
editor displays the line as changed. 

11 Use the BOTTOM subcommand to move the current line pointer to point to the last line 
in the file. Enter input node with the INPUT subcommand. 

12 If you enter input mode and decide that you do not want to enter input lines, all 
you have to do to return to edit mode is enter a null line. 

13 To write the file onto disk, use the FILE subcommand. This writes it onto disk 
using the name with which you invoked the editor, COMMAND DATA. The CMS ready 
message indicates that you are in the CMS command environment. 
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14 type command data 

COPYFILE COPY CHS FILES 

SORT SORT CMS FILES IN ALPHAMERIC ORDER BY SPECIFIC COLUMNS 



TAPE LOAD READ CMS FILES ONTO DISK FROM TAPE 

K; 

15 edit command data 

EDIT: 
16 



save 
EDIT: 

17 fname comm2 
file 

R; 

18 copyfile comffl2 data a (lowcase 

R; 

19 copyfile command data a comm2 data a (ovly specs 
DMSCPY601R ENTER SPECIFICATION LIST: 

1-12 1 

R; 

20 type comm2 data 

COPYFILE Copy cms files 

SORT Sort cms files in alphameric order by specific columns 

EDIT Create a cms file 

EDIT Modify a cms file 

RENAME Change the name of a cms file 

PUNCH Punch a copy of a cms file on cards 

PRINT Print a cms file 

ERASE Erase a cms file 

LISTFILE List information on a cms file 

21 ht 
R; 



m To display the entire file at your terminal, use the CMS TYPE command. Note any 
errors that you made that you might want to correct. 

15 Use the EDIT command to edit the file COMMAND DATA again. This time, since the file 
exists, the editor does not issue the message, NEW FILE: 

16 While you are in edit mode, make any changes that you need to; then issue the SAVE 
subcommand to save these changes, and replace the existing copy of the file onto 
disk. 

17 Use the FNAME subcommand to change the filename of the file to C0MM2 (the filetype 
remains unchanged) . When you issue the FILE subcommand this time, the file is 
written onto disk with the name C0MM2 DATA- 

18 You can rewrite the entire file, C0MM2 DATA in lowercase characters, using the 
COPYFILE command with the LOWCASE option. 

19 The file C0MM2 DATA is now all lowercase characters (you can display the file with 
the TYPE command if you want to verify it) . However, the command names, and the 
first character of the description should be uppercase characters. You can use the 
COPYFILE command again, to overlay the original uppercase characters of COMMAND DATA 
in columns 1 through 12 over the lowercase characters in columns 1 through 12 of 
C0MM2 DATA. 

20 Use the TYPE command to verify that the COPYFILE command did, in fact, overlay only 
the columns that you wanted. 

21 The HT Immediate command suppresses the display of the remainder of the file; you 
can see from the first few lines that the format of the file is correct. 
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22 listfile * data 

I COHHAND DATA Al 
I C0MM2 DATA Al 

R; 

23 sort conini2 data a command sort a 
DMSSRT60UR ENTER SORT FIELDS: 

1 9 

R; 

24 type command sort 

COMPARE Verify that two files are identical 
COMPARE Compare the contents of cms disk files 



TYPE Display the contents of a cms file at your terminal 

R; 

25 copyfile comm2 data a function data a ( specs 
DMSCPY601R ENTER SPECIFICATION LIST: 

12-72 1 1-9 70 

R; 

26 type function data 

Copy cms files COPYFILE 

Sort cms files in alphameric order by specific columns SORT 



Read cms files onto disk from tape TAPE LOAD 

R; 
27 sort function data a function sort a 
DMSSRT604R ENTER SORT FIELDS: 
1 70 

R; 

type function sort 

Alter the name of a cms file RENAME 

Change the name of a cms file RENAME 



Verify the existence of a cms file on a read/write disk STATEH 

R; 



22 The LISTFILE command lists your two files with the filetype of DATA. (If you 
previously had files with these filetypes, they are also listed.) 

23 To sort the file C0MM2 DATA into alphabetic order, by command, issue the SORT 
command. Hhen you are prompted for the sort fields, enter the columns that contain 
the command names, 1 through 9. 

24 The output file from the SORT command is named COMMAND SORT. You can use the TYPE 
command to verify that the records are now sorted alphabetically by command. 

25 To create another copy of the file, this time with the command names on the right 
and the functional description on the left, use the COPYFILE command with the SPECS 
option again. To create a file this way, you must know the columns in your input 
file (C0MM2 DATA) and how you want them arranged in your output file (FUNCTION 
DATA). Columns 1 through 9 contain the command names; columns 12 through 72 contain 
the descriptions. The specification list entered after the prompting message 
indicates that columns 12 through 72 should be copied and placed beginning in column 
1, and that columns 1 through 9 should be copied beginning in column 70. 

26 Verify the COPYFILE operation with the TYPE command. 

27 Sort the file FUNCTION DATA so that the functional descriptions appear in alphabetic 
order. You may also want to display the output file, FUNCTION SORT. 
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28 


listfile 

COMMAND DATA Al 
C0MM2 DATA Al 
COMMAND SORT Al 
FUNCTION DATA Al 
FUNCTION SORT Al 

R; 

erase command data 

R; 

rename comm2 data a coi 

R; 

listfile * * a ( label 
FILENAME FILETYPE FM 
FUNCTION SORT Al 
COMMAND DATA Al 
COMMAND SORT Al 
FUNCTION DATA Al 














29 














30 


amand data a 












FORMAT 

F 

F 

F 

F 


LRECL 
80 
80 
80 
80 


RECS 
22 
22 
22 
22 


BLOCKS 
3 
3 
3 
3 


DATE 
10/13/75 
10/13/75 
10/13/75 
10/13/75 


TIME LABEL 
7:52:03 ABC191 
7:48:52 ABC191 
7:48:15 ABC191 
7:51:37 ABC191 


31 
32 

33 


edit function sort 

EDIT: 

zone 

1 80 
zone 60 

change / // * 
Alter the name of a cms file 
Change the name of a cms file 










RENAME 
RENAME 


34 
35 


• 

Verify the existence of a cms 

EOF: 

top 

TOF: 

find List 

NOT FOUND 

EOF: 


file on 


a rea 


d/write 


disk 


STATEH 




case 

U 
case m 
find List 
List information on a c 
















:ms file 










LISTFILE 



28 

29 

30 

31 
32 



33 



34 



35 



If these are the only files on your A-dis 
operands produces a list of the files creat 
The file C0MM2 was created for a workfile. 
Since you no longer need the original file. 
Use the RENAME command to rename the workf 
DATA- The LISTFILE command verifies the ch 
To begin altering the file FUNCTION SORT, i 
The ZONE command requests a display of the 
1 and 80. When you issue the command ZONE 
and 80, so that you cannot modify data in c 
The CHANGE subcommand requests that the fi 
on each line in the file be compressed. 
CHANGE request by displaying each line chan 
net effect is to shift the command column 5 
Position the current line pointer at the 
subcommand to move the line pointer to the 
The editor indicates that the line is not 
the CASE subcommand, you can see that it 
the editor is translating your input data 
subcommand to change this setting, then rei 



k, the LISTFILE command entered with no 
ed so far. 

in case any errors might have happened. 

COMMAND DATA, you can erase it. 
ile C0MM2 DATA to have the name COMMAND 
ange. 
nvoke the editor again. 

current zone settings, which are columns 
60, it changes the settings to columns 60 
olumns 1 through 59. 

rst appearance of five consecutive blanks 
The editor displays the results of this 
ged (which is each line in the file) . The 

spaces to the left, 
top of the file, and then issue a FIND 
line that begins with "List". 

found. Checking the current setting for 
is U, or uppercase, which indicates that 

to uppercase. You can issue the CASE M 
ssue the FIND subcommand. 
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36 change /on a cis/about a CHS 
NOT FOOND 

= zone 1 * 

37 List information about a CMS file 
top 

TOF: 

38 change /cms/CMS/ * 

Alter the nane of a CHS file 
Change the name of a CHS file 



LISTFILE 



RENAHE 
RFNAHE 



Verify the existence of a CMS file on a read/write disk 

EOF: 
39 save 

EDIT: 

top 

TOF: 

next 
UO Alter the name of a CMS file 

$dap 

Alter the name of a CMS file 

change /name/f iletype/ 

Alter the filetype of a CMS file 

next 
41 Change the name of a CHS file 

change /name/filename/ 

Change the filename of a CHS file 

next 
t»2 Compare the contents of CHS disk files 

next 

Copy CHS files 

43 find H 

Hodify a CHS file 

up 

List information about a CHS file 

44 i Make a copy of a CHS disk file 
top 

TOF: 



STATEW 



RENAME 
RENAHE 

RENAHE 
RENAME 

RENAHE 

CCHFARE 

COPYFILE 

EDIT 

LISTFILE 
COPYFILE 



36 



37 
38 
39 

40 



41 
42 
43 



44 



Jr 



The editor locates the line and displays it. You nant to change the character string 

"on a cms" to "about a CHS". The editor does not find the string you specify because 

the zone setting for columns 60 through 80 is still in effect. You can enter the 

ZONE subcommand, and reissue the CHANGE subcommand, or you can enter the = (REUSE) 

subcommand to stack the CHANGE subcommand, and enter the ZONE subcommand to execute 

first. 

The ZONE subcommand is executed, then the CHANGE subcommand. The editor displays the 

changed line. 

At the top of the file, enter another global change request, to change lowercase 

occurrences of the string cms to uppercase. The editor displays each line changed. 

When the EOF: message indicates that the end of the file is reached, you can save 

the changes made during this edit session with the SAVE subcommand before 

continuing. 

Hove the current line pointer to point to the first line in the file. You want to 

add an entry that is similar; use the $DDP edit macro to duplicate the line, then 

change the copy that you made of the line. 

You can change the word name to filename in the next line also. 

You can scan a file, a line at a time, by issuing successive NEXT subcommands. 

To insert a line beginning with the character H, and to maintain alphabetic 

sequencing, use the FIND subcommand to find the first line beginning with an H. The 

line to be inserted begins with the characters HA, so you want to move the line 

pointer up. 

You can insert a single line into a file with the INPUT subcommand. Here, the INPUT 

subcommand is truncated to I, so that when you space over to write the command name 

in the right column, you can align it (you only have to allow for the two character 

spaces use by "i ". 
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45 /COPYFILE 
Copy CMS files 

46 n 

Create a CMS file 

n 

Display the contents of a CMS file at your terminal 

n 

Dump CMS files onto tape 

n 

Erase a CHS file 

47 up 3 

Create a CMS file 

i Delete a file from a CMS disk 

file 

R; 

48 type function sort a 

Alter the name of a CMS file 
Alter the filetype of a CMS file 
Change the filename of a CMS file 



COPYFILE 

EDIT 

TYPE 

TAPE DUMP 

ERASE 

EDIT 
EBASE 



RENAME 

RENAME 
RENAME 



Verify the existence of a CMS file on a read/write disk 



R; 
49 edit function sort 
zone 58 

change / // * * 
Alter the name of a CMS file 
Alter the filetype of a CMS file 
Change the filename of a CMS file 



STATEH 



RENAME 
RENAME 
RENAME 



Verify the existence of a CMS file on a read/write disk STATEH 



EOF 
50 top 
TOF: 

change //I / * 

Alter the name of a CMS file 
Alter the filetype of a CMS file 
Change the filename of a CMS file 



I RENAME 
I RENAME 
I RENAME 



Verify the existence of a CMS file on a read/write disk 
EOF: 



STATEW 



45 

46 
47 



48 
49 



50 



Move the line pointer to the top of the file and begin scanning again. A diagonal 

(/) is interpreted as a LOCATE subcommand. 

The NEXT subcommand can be truncated to "N". 

In front of the line beginning "Display", insert a line beginning with "Delete". If 

you want to make any other modifications, do so. Otherwise, write this file onto 

disk with the FILE subcommand. 

Verify your changes. 

Edit the file again. To compress unnecessary spaces in right hand columns, change 

the zone setting. This time, issue a CHANGE subcommand that will delete all blank 

spaces occuring after column 58. Since some changes you made to the file might have 

spoiled the alignment in the command column, this CHANGE subcommand should realign 

all of the columns. 

Return the current line pointer to the top of the file. Change a null string to the 

string "| " for all lines in the file; since the left zone is still column 58, the 

characters are inserted in columns 58 and 59. 



( 
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51 zone 1 * 

top 

TOF: 

c //I / * 

Alter the name of a CMS file 
Alter the filetype of a CMS file 
Change the filename of a CMS file 



I RENAME 
I RENAME 
I RENAME 



Verify the existence of a CMS file on a read/write disk 
EOF: 
52 top 
TOF: 
next 

Alter the name of a CMS file 
tabset 72 
repeat * 
overlay I 

Alter the name of a CMS file 

Alter the filetype of a CMS file 

Change the filename of a CMS file 

Compare the contents of CMS disk files 



I STATEW 



I RENAME 



I RENAME 

i RENAME 

I RENAME 

I COMPARE 



Verify the existence of a CMS file on a read/write disk | STATEW 
EOF: 
bottom 

Verify the existence of a CMS file on a read/write disk | STATEW 
53 input 
SU zone 1 72 

c / /-/ 1 * 



55 



56 



top 

TOF: 

input 

c / /-/ 1 * 



file 

R; 

print function sort 

R; 



/ 



51 



52 



53 



5U 



55 
56 



Change the left zone setting to column 1 and let the r 

record length; issue the CHANGE subcommand to insert th 

CHANGE can be abbreviated as "C". 

At the top of the file, change the TABSET subcommand 

column 72 the left margin. The REPEAT ♦ subcommand, 

subcommand, indicates that all the lines in the file are 

the leftmost column (column 72) . 

When you enter this INPUT subcommand, enter a number of 

this places a blank line in the file. 

Reset the ZONE setting to columns 1 and 72. The CHANGE su 

blanks on this line should be changed to hyphens (-) . 

specified zone are changed. 

Insert another blank line at the top of the file and chan 

Write the file onto disk and use the CMS PRINT comman 

offline printer. 



ight zone be equal to the 
e "I" in columns 1 and 2. 

setting to 72. This makes 

followed by the OVERLAY 

to be overlaid with a | in 

blank spaces following it; 

bcommand indicates that all 
Only the blanks within the 

ge it to hyphens. 

d to spool a copy to the 
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Sample Terminal Session Using Line-Number Editing 



This terminal session shows how a terminal session using right-handed line-number editing 
might appear on a typewriter terminal. The commands function the same way on a display 
terminal, but the display is somewhat different. When you enter these input lines, you 
should have physical tab stops set at your terminal at positions 16 and 22 (for assembler 
columns 10 and 16; the difference compensates for the line numbers, as you will see). On 
a display terminal, tab settings have no significance; once the line is in the output 
display area, it has the proper number of spaces. 



1 


edit test aasei 


Bble 




NKW FILE: 








EDIT: 






2 


linemode right 






input 








INPUT: 






3 


00010 * sample 


of linemode right 




00020 test 




csect 




00030 




balr 12,0 




00040 




using *,12 




00050 




St 14,sav14 




00060 




wrterm testing... 




00070 




1 14,sav14 




00080 




br 14 




00090 




end 




00100 






4 


EDIT: 






5 


60 








00060 




WRTERH 


6 


c /testing. 


,../ 


'testing.. . ' 




00060 




WRTERM 


7 


80 








00080 




BR 14 




input 








INPUT: 







TESTING... 
'TESTING... • 



1 Use the EDIT command to invoke the CHS editor. Since this is a n 
issues the NEW FILE message. 

2 Issue the LINEMODE subcommand to indicate that you want to 
editing.. For ASSEMBLE files, you cannot have line numbers on th 
assembler expects data in columns 1 through 7. 

3 As soon as you issue the INPUT subcommand, the editor begins pro 
input lines. For convenience in entering lines, the line numbers 
as they would if you were using left-handed line-number editing, 
file, however, the line numbers are actually on the right. 

4 When you are have finished entering these input lines, enter a 
to edit mode from input mode. 

5 To locate lines when you are using line-number editing, you 
number of the line. In this case, enter 60 to position the curr 
the line numbered 00060. The editor displays the line. 

6 Issue the CHANGE subcommand to place quotation marks around the 
WRTERM macro. The editor redisplays the line, with the change. 

7 Issue the nnnnn subcommand, specifying line number 80, and use t 
so you can begin entering more input lines. 



ew file, the editor 

begin line-number 
e left, because the 

mpting you to enter 

appear on the left. 

In your ASSEMBLE 

null line to return 

can enter the line 
ent line pointer at 

text line for the 

he INPUT subcommand 



( 
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8 


00083 sav14 


ds 


f 




00085 vkarea 


ds 


3d 




00087 flag 


ds 


X 




00088 ranon 


equ 


x»80« 




00089 runoff 


equ 


x'UO* 


9 


BENUHBER LINES 








EDIT: 








linemode off 








serial on abc 








save 






10 


EDIT: 






11 


lineiode right 
type 








00030 RUNOFF 


EQU 


X«UO» 


12 


verify 1 * 
type 








00030 RUNOFF 


EQU 


X»UO« 


13 


135 


runiix equ x«20« 


Mi 


50 








00050 


ST 


14,SAV1U 




input 








INPUT: 








00053 


tn 


flag^runon 




00055 


bcr 


1,14 




00057 






15 


EDIT: 
top 
TOF: 
next 








* SAMPLE OF LINEMODE RIGHT 


16 


restore 







ABC00130 
ABC00050 



ABC00010 



10 
11 

12 



13 



> 



14 



15 



16 



When you begin entering input lines between two existing lines, the editor uses an 

algorithm to assign line numbers. 

The editor ran out of line numbers, since the next line in the file is already 

numbered 90. You must renumber the lines. Before you can renumber the lines, you 

must turn line-number editing off. Before issuing the SAVE subcommand, which writes 

the file and its new line numbers onto disk, you can issue the SERIAL subcommand. 

SERIAL ABC indicates that you want the characters ABC to appear as the first three 

characters of each serial number. 

The EDIT message indicates that the SAVE request has completed. 

Issue the LINEMODE subcommand to restore line-number editing. Use the TYPE 

subcommand to verify the position of the current line pointer. 

If you want to see the serial numbers in columns 72 through 80, issue the VERIFY 

subcommand, specifying *, or the record length. Normally, the editor does not 

display the columns containing serial numbers while you are editing. 

You can use the nnnnn subcommand to insert individual lines of text. This subcommand 

inserts a line that you want numbered 135, and places it in its proper position in 

the file. Note that although, in this example, the current line pointer is 

positioned at line 130, it does not need to be at the proper place in the file. When 

the subcommand is complete, however, the current line pointer is positioned 

following the line just inserted. 

Position the line pointer at the line numbered 50, and again begin entering the 

input lines indicated. 

Enter a null line to return to edit mode, move the current line pointer to the top 

of the file, and display the first line. 

The RESTORE subcommand restores the default settings of the editor, and the the 

verification columns are restored to 1 and 72, so that line numbers are not 

displayed in columns 72 through 80. 
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17 



18 



19 



type * 








* SAMPLE 


OF LINEMODE RIGHT 




TEST 


CSECT 








BALR 


12,0 






USING 


*,12 






ST 


n,SA?14 






TM 


FLAG,RUNON 






BCR 


1,14 






WRTERM 


•TESTING 




L 


U,SAVia 






BR 


14 




SAV14 


DS 


F 




WKAREA 


DS 


3D 




FLAG 


DS 


X 




RONON 


EQU 


X»80» 




RUNOFF 


EQU 


X'40» 




RONMIX 


EQU 
END 


X»20» 




EOF: 








file 








RESERIALIZATION SUPPRESSED 




R; 








type test assei 


able 




* SAMPLE 


OF LINEMODE RIGHT 




TEST 


START 


X»20000« 






BALR 


12,0 






USING 


*,12 






ST 


14,SAV14 






TM 


FLAG,RUNON 






BCR 


1,14 






TYPE 


•TESTING...' 






L 


14,SAV14 






BR 


14 




SAvia 


DS 


F 




WKAREA 


DS 


3D 




FLAG 


DS 


X 




RONON 


EQU 


X«80' 




RUNOFF 


EQU 


X«40« 




RUNMIX 


EQU 
END 


X»20» 





ABC00010 
ABC00020 
ABC00030 
ABC00040 
ABC00050 
00053 
00055 
ABC00060 
ABC00070 
ABC00080 
ABC00090 
ABC00100 
ABC00110 
ABC00120 
ABC00130 
00135 
ABC00140 



17 

18 



19 



Use the TYPE subcoBmand to display the file. 

When you issue the FILE subcommand to write the file onto disk, the editor issues 

the message RESERIALIZATION SUPPRESSED to indicate that it is not going to update 

the line numbers, so that the current line numbers match the line numbers as they 

existed when the SAVE subcommand was issued. 

If you want to see how the file exists on disk, use the CMS TYPE command to display 

the file. Note that the lines inserted after the SAVE subcommand do not have the 

initial ABC characters, and that they retain the line numbers they had when they 

were inserted. 



I 
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Sample Terminal Session for OS Programmers 



The following terminal session shows how you might create an assembler language program 
in CMS, assemble it, correct assembler errors, and execute it. All the lines that appear 
in lowercase are lines that you should enter at the terminal. Uppercase data represents 
the system response that you should receive when you enter the command. 

The input data lines in the example are aligned in the proper columns for the 
assembler; if you are using a typewriter terminal, you should set your terminal's tab 
stops at columns 10, 16, 31, 36, 41, and 46, and use the Tab key when you want to enter 
text in these columns. If you are using a display terminal, when you use a PF key defined 
as a tab, or some input character, the line image is expanded as it is placed in the 
screen output area. 

There are some errors in the terminal session, so that you can see how to correct 
errors in CMS. 

1 edit ostest assemble 
MEW FILE: 
EDIT: 
input 
INPUT: 
dataproc csect 

print nogen 

space 

rO egu 

r1 equ 1 

r2 equ 2 

rIO equ 10 

r12 equ 12 

r13 equ 13 

r14 equ 14 

r15 equ 15 

space 

stm r14,r12, 12(r13) save caller's regs 

balr r12,0 establish 

using *,r12 addressability 

st r13,savearea*4 store addr of caller's savearea 

la r15, savearea get the address of my savearea 

st r15,8(r13) store addr in caller's savearea 

Ir r13,r15 save addr of my savearea 

space 
♦open files and check that they opened okay 

space 

la r3,0 initially set return code 

open (indata,outdata, (output) ) open files 

using ihadcb,r10 get dsect to check files 

la r10,indata prepare to check output file 

ta dcboflgs,x' 10' everything ok? 

bnz checkout ...continue 

la r3,100 set return code 

b exit ...exit 

checkout la r10,outdata check output file 

tm dcboflgs,x' 10' is it okay? 

bnz process ... 

la r3,200 set return code 

b exit 



) 



The EDIT command is issued to create a file named OSTEST ASSEMBLE. Since the file 
does not exist, the editor indicates that it is a new file and you can use the INPUT 
subcommand to enter input mode and begin entering the input lines. 
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space 
process egu 
get 
Ir 
put 
b 

space 
exit egu 

close 
1 

Ir 
1 

Iffl 
br 

space 
savearea dc 
Indata deb 

EDIT: 

$nark 

save*input 

EDIT: 

INPUT: 



outdata 



deb 
dcbd 
space 
end 



indata 
r2,r1 

outdata, (2) 
process 



read a record from input file 
save address of record 
move it to output 
continue until end-of-file 



(indata,, outdata) close files 
r13,savearea+U addr of caller's save area 
r15,r3 load return code 
r14,12(r13) get return address 
r0,r12,20(r13) restore regs 
r14 bye... 

18f«0« 

ddname=indd,macrf=gl,dsorg=ps,recfm=f ,lrecl=80. 



eodad=exit 
ddname=outdd,macrf=pm,dsorg=ps 



EDIT: 
file 

R; 

5 global maclib osmacro 
R; 

6 assemble ostest 

* 
* 

* 

* 



Since the DCB macro statement takes up more than one line, you have to enter a 

continuation character in column 72. To do this, you can enter a null line to return 

to edit mode and execute the SHARK edit macro, which places an asterisk in column 

72. If the SHARK edit macro is not on your system, you will have to enter a 

continuation character some other way. (See "Entering a Continuation Character in 

Column 72" in "Section 5. The CHS Editor.") 

Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write 

what has already been written onto disk. The CP logical line end symbol (#) 

separates the SAVE and INPUT subcommands. 

A null line returns you to edit mode. You may wish, at this point, to proofread 

your input file before issuing the FILE subcommand to write the ASSEMBLE file onto 

disk. 

Since this assembler program uses OS macros, you must issue the GLOBAL command to 

identify the CHS macro library, OSHACRO HACLIB, before you can invoke the assembler. 

The ASSEHBLE command invokes the VH/370 assembler to assemble the source file; the 

asterisks (*) indicate the CHS blip character, which you may or may not have made 

active for your virtual machine. 



i 
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INITIALLY SET RETORN CODE 



ASSEMBLER DONE 

OST00230 23 LA R3,0 

IF0188 R3 IS AN UNDEFINED SYMBOL 

OST002U0 24 OPEN (INDATA,OUTEATA, (OUTPUT) ) OPEN FILES 

4000000 27+ 12,*** IHB002 INVALID OPTION OPERAND SPECIFIED-OUTDATA 
IF0197 *** MNOTE *** 

OST00290 32 LA R3,100 SET RETURN CODE 

IF0188 R3 IS AN UNDEFINED SYMBOL 

OST00340 37 LA R3,200 SET RETURN CODE 

IF0188 R3 IS AN UNDEFINED SYMBOL 

OST00460 63 LR R15,R3 LOAD RETURN CODE 

IF0188 R3 IS AN UNDEFINED SYMBOL 

NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY = 5 
R (00012) ; 

edit ostest assemble 
locate /r2 
R2 EQU 2 
i r3 equ 3 
/open 

OPEN (INDATA,OUTDATA, (OUTPUT)) OPEN FILES 
c /,/,,/ 

OPEN (INDATA,,OUTDATA, (OUTPUT)) OPEN FILES 
file 

R; 

assemble ostest 

* 

* 

* 

* 



10 ASSEMBLER DONE 

NO STATEMENTS FLAGGED IN THIS ASSEMBLY 

R; 

11 filedef indd disk test data a 

R; 

12 filedef outdd punch 
R; 

13 #cp spool punch to * 



7 The assembler di 
accurately you cop 
some of these mess 

8 You must edit the 
placed in the exam 
of an EQU statemen 
CMS editor accepts 

9 After all the cha 
subcommand to repl 

10 This time, the a 
ASSEMBLE file stil 

11 The FILEDEF comma 
program. The ddnam 
file definition i 
A-disk name TEST 
have no such file. 



splays errors encountered during assembly. Depending on how 
ied the program in this sample session, you may or may not receive 
ages; you may also have received additional messages. 

file OSTEST ASSEMBLE and correct any errors in it. The errors 
pie included a missing comma on the OPEN macro, and the omission 
t for a general register. These changes are made as shown. The 

a diagonal (/) as a LOCATE subcommand, 
nges have been made to the ASSEMBLE file, you can issue the FILE 
ace the existing copy on disk, and then reassemble it. 
ssembler completes without encountering any errors. If your 
1 has errors, you should use the editor to correct them, 
nd is used to define the input and output files used in this 
es INDD and OUTDD, defined in the DCBs in the program, must have a 
n CMS. To execute this program, you should have a file on your 
DATA, which must have fixed-length, 80-character records. If you 

you can make a copy of your ASSEMBLE file as follows: 



copyfile ostest assemble a test data a 

12 The output file is defined as a punch file, so that it will be written to your 
virtual card punch. 

13 The CP SPOOL command is issued, using the #CP function, to spool your virtual punch 
to your virtual card reader. When you use the #CP function, you do not receive a 
Ready message. 
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11 load ostest 

R; 

start 

DMSLIO7U0I EXECUTION BEGINS... 

15 DMSSOP036E OPEN ERROR CODE 'OU* ON »O0TDD «. 
R (00200) ; 

16 filedef 

INDD DISK TEST DATA Al 
OOTDD PUNCH 

R; 

17 filedef outdd punch (Irecl 80 recfm f 

R; 

18 #cp query reader all 
NO RDR FILES 

19 load ostest (start 
DMSLIO740I EXECUTION BEGINS... 

20 PUN FILE 6198 TO BILBO COPY 01 NOHOLD 

R; 

21 fi indd reader 

R; 

fi outdd disk new osfile a4 (recfm fb block 1600 Irecl 80 

R; 

22 listfile new osfile aU (label 
DMSLST002E FILE NOT FOUND. 

R (00028) ; 

23 run ostest 
EXECUTION BEGINS... 

R; 

24 listfile new osfile a4 (label 

FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS DATE TIME LABEL 
NEW OSFILE AU F 1600 5 10 9/30/75 8:26:14 PAT198 

R; 



14 The LOAD command loads the TEXT file produced by the assembly into virtual storage. 
The START command begins program execution. 

15 An open error is encountered during program execution. The CMS ready message 
indicates a return code of 200, which is the value placed in it by your program. 

16 The FILEDEF command, with no operands, results in a display of the current file 
definitions in effect. 

17 Error code 4 on an open request means that no RECFM or LRECL information is 
available. An examination of the program listing would reveal that the DCB for 
OUTDD does not contain any information about the file format; you must supply it on 
the FILEDEF command. Re-enter the FILEDEF command. 

18 You can use the CP QUERY command to determine whether there are any files in your 
card reader. It should be empty; if not, determine whether they might be files you 
need, and if so, read them into your virtual machine; otherwise, purge thero. 

19 Use the LOAD command to execute the program again; this time, use the START option 
of the LOAD command to begin the program execution. 

20 The PUN FILE message indicates that a file has been transferred to your virtual card 
reader. The ready message indicates that your program executed successfully. 

21 For the next execution of this program, you are going to read the file back out of 
your card reader and create a new CMS disk file, in OS simulated data set format. 
FI is an acceptable system truncation for the command name, FILEDEF. 

22 The LISTFILE command is issued to check that the file NEW OSFILE does not exist. 

23 The RUN command (which is an EXEC procedure) is used instead of the LOAD and START 
commands, to load and execute the program. The ready message indicates that the 
program completed execution. 

24 The LISTFILE command is issued again, and the file NEW OSFILE is listed. (If you 
issue another CP QUERY READER command, you will also see that the file is no longer 
in your card reader.) 
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Sample Terminal Session for DOS Programmers 



The following terminal session shows how you might create an assembler language program 
in CMS, assemble it, correct assembler errors, and execdte it. All the lines that appear 
in lowercase are lines that you should enter at the terminal. Uppercase data represents 
the system response that you should receive when you enter the command. 

The input data lines in the example are aligned in the proper columns for the 
assembler; if you are using a typewriter terminal, you should set your terminal's tab 
stops at columns 10, 16, 31, 36, 41, and 46 and use the Tab key when you want to enter 
text in these columns. If you are using a display terminal, when you use a PF key or an 
input character defined as a tab, the line image is expanded as it is placed in the 
screen output area. 

I No te ; The assembler, in CMS, cannot read macros from DOS/VSE libraries. This sample 
I terminal session shows how to copy macros from BOS/VSE libraries and create CMS MACLIB 
files. Ordinarily, the macros you need should already be available in a system MACLIB 
file. You do not have to create a MACLIB each time you want to assemble a program. 

There are some errors in the terminal session, so that you can see how to correct 
errors in CMS. 



1 


cp link 


dosres 


130 130 rr linkdos 




DASD 13C 


1 LINKED R/0 




R; 








access 130 z 






Z (130) 


R/0 - DOS 




R; 






2 


set dos 

R; 


on z 




3 


edit dostest assemble 




NEW FILI 


!: 






EDIT: 








input 








INPUT: 








begpgm 


csect 








balr 


12,0 






using 


*,12 






la 


13,savearea 






open 


inf ile,outf ile 




loop 


get 


inf ile 






put 


outfile 






b 


loop 




eodad 


equ 


* 



buffer 
infile 



close inf ile, outfile 

eoj 

eject 

dc CL80» • 

dtfdi modname=shrmod,ioarea1=buffer,devaddr=sysipt. 



1 Use the CP LINK command to link to the DOS system residence volume and the ACCESS 
command to access it. In this example, the system residence is at virtual address 
130 and is accessed as the Z-disk. 
I 2 Enter the CMS/DOS environment, specifying the mode letter at which the DOS/VSE 
system residence is accessed. 

3 Use the EDIT command to create a file named DOSTEST ASSEMBLE. Since the file does 
not exist, the editor indicates that it is a new file and you can use the INPUT 
subcommand to enter input mode and begin entering the input lines - 



Sample Terminal Session for DOS Programmers 369 



March 30, 1979 



EDIT: 

Smark 

savetinput 

EDIT: 

INPUT: 

eof aadr=eodad, recsize=80 
outfile dtfdi niodDaiBe=shrmod,ioarea1=buffer,devaddr=syspch, 

EDIT: 

$mark 

save#input 

EDIT: 

INPUT: 

recsize=81 
shrmod dimod typef le=output 
endpgm equ * 
end 



EDIT: 
file 

R; 

8 edit getmacs eserv 
NEW FILE: 

EDIT: 
tabs 2 72 
input 
INPUT: 

9 punch open, close, get, put, dimod, dtfdi 

EDIT: 
file 

R; 

10 assgn sysipt a 

R; 

eserv getmacs 

R; 



4 Since the DTFDI macro statement takes up more than one line, you have to enter a 
continuation character in column 72. To do this, you can enter a null line to return 
to edit mode and execute the $MARK edit macro, which places an asterisk in column 
72. If the $MARK edit macro is not on your system, you will have to enter a 
continuation character some other way. (See "Entering a Continuation Character in 
Column 72" in "Section 5- The CMS Editor.") 

5 Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write 
what has already been written onto disk. The CP logical line end symbol (#) 
separates the SAVE and INPUT subcommands. 

6 Another continuation character is needed. 

7 A null line returns you to edit mode. You may want, at this point, to proofread your 
input file before issuing the FILE subcommand to write the ASSEMBLE file on disk. 

8 To obtain the macros you need to assemble this file, use the editor to create an 
ESERV file. By setting the logical tabs at columns 2 and 72, you can protect 
yourself from entering data in column 1. 

9 PUNCH is an ESERV program control statement that copies and de-edits macros from 
source statement libraries; in this case, the system source statement library. The 
output is directed to the SYSPCH device, which the CMS/DOS ESERV EXEC assigns by 
default to your A-disk. 

10 You must assign the logical unit SYSIPT before you invoke the ESERV command. GETMACS 
is the filename of the ESERV file containing the ESERV control statements. 
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11 listfile getmacs * 

I GETMACS ESERV Al 

I GETMACS MACRO Al 

I GETMACS LISTING Al 

B; 

12 maclib gen dosmac getmacs 

R; 

erase getmacs * 

R; 

13 global maclib dosmac 

R; 

14 assemble dostest 

15 ASSEMBLER DONE 

DOSOOOUO U LA 13,SAVEAREA 

IF0188 SAVEAREA IS AN UNDEFINED SYMBOL 

DOS00110 35 EOJ 

IFO078 UNDEFINED OP CODE 

NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY = 

R (00008) ; 

16 edit detest assemble 
EDIT: 

locate /buffer/ 

BUFFER DC CL80« • 

input savearea ds 9d 

file 

E; 

17 edit eoj eserv 
NEW FILE: 
EDIT: 

i punch eoj 
file 

R; 

18 listio sysipt 

SYSIPT DISK A 

R; 

eserv eoj 

R; 



11 After the ESERV EXEC completes execution, you have three files. You may want to 
examine the LISTING file to check the ESERV program listing. The MACRO file 
contains the punch (SYSPCH) output. 

12 The MACLIB command creates a macro library named DOSMAC MACLIB. Since the MACLIB 
command completed successfully, you can erase the files GETMACS ESERV^ GETMACS 
LISTING, and GETMACS MACRO; an asterisk in the filetype field of the ERASE command 
indicates that all files with the filename cf GETMACS should be erased. 

13 Before you can invoke the assembler, you have to identify the macro library that 
contains the macros; use the GLOBAL command, specifying DOSMAC MACLIB. 

1U The ASSEMBLE command invokes the VM/370 assembler to assemble the source file; the 
asterisks (*) indicate the CMS blip character, which you may or may not have made 
active for your virtual machine. 

15 The assembler displays errors encountered during assembly. Depending on how 
accurately you copied the program in this sample session, you may or may not receive 
some of these messages; you may also have received additional messages. 

16 To correct the first error, which was the omission of a DS statement for SAVEAREA, 
edit the file DOSTEST ASSEMBLE and insert the missing line. 

17 The second error indicates that the macro EOJ is not available, since it was not 
copied from the source statement library. Create another ESERV file to punch this 
macro. 

18 Use the LISTIO command to check that SYSIPT is still assigned to your A-disk, so 
that you do not have to issue the ASSGN command again. Then issue the ESERV command 
again, this time specifying the filename EOJ. 
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19 



20 



21 



22 



23 



24 



maclifc add dosmac eoj 

R; 

maclifc map dosmac (term 



MACRO INDEX SIZE 




OPEN 2 


43 




CLOSE 46 


43 




GET 90 


56 




PUT 147 


93 




DIMOD 241 


647 




DTFDI 889 


284 




EOJ 1174 


6 




R; 






erase eoj * 
R; 

assemble dostest 

* 

* 










* 

ASSEMBLER DONE 






NO STATEMENTS FLAGGED IN THIS 


ASSEMBLY 


R; 

listfile dostest 


* 




DOSTEST ASSEMBLE 


: Ai 




DOSTEST LISTING 


A1 




DOSTEST TEXT 


AI 




R t 

print dostest listing 




R; 






doslked dostest 

R; 

listfile dostest 






* 




DOSTEST ASSEMBLE 


! AI 




DOSTEST DOSLIB 


AI 




DOSTEST TEXT 


AI 




DOSTEST LISTING 


AI 




DOSTEST MAP 


A5 




R; 







19 Use the ADD function of the MACLIB command to add the macro EOJ 
Then, issue the MACLIB command again* using the MAP function and 
display a list of the macros in the library. 

20 Erase the EOJ files. You should always remember to erase files th 
any longer. Reassemble the program. 

21 This time, the assembler completes without encountering any 
ASSEMBLE file still has errors, you should use the editor to corre 

22 Use the LISTFILE command to check for DOSTEST files. The asse 
files, DOSTEST LISTING and DOSTEST TEXT. The TEXT file contains 
You can print the program listing, if you want a printed copy. The 
erase it. 

23 Use the DOSLKED command to link-edit the TEXT file into an exe 
write it into a DOSLIB. Since this program has no external refe 
need to add any linkage editor control statements. 

24 Now, you have a DOSTEST DOSLIB, containing the link-edited phase 
containing the linkage editor map. You can display the linkage e 
TYPE command, or use the PRINT command if you want a printed copy. 



to DOSMAC MACLIE. 
the TERM option to 

at you do not need 

errors. If your 
ct them. 

mbler created the 
the object module, 
n, you may want to 

cutable phase and 
rences, you do not 

, and a MAP file, 
ditor map with the 
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COPY 01 NOHOLD 



CPY HOLD DATE TIME NAME 
01 NONE 09/29 15:00:39 TEST 



25 #cp spool punch to * 
punch test data a 
PUN FILE 0100 TO BILBO 

H; 

#cp query reader all 
ORIGINID FILE CLASS RECDS 
PATTI 5840 A PON 000097 

26 assgn sysipt reader 

R; 

assgn syspch a 

R; 

27 dlbl outfile a cms punch output (syspch 

R; 

state punch output a 
DMSSTT002E FILE NOT FOUND. 
R (00028) ; 

28 global doslib dostest 
R; 

fetch dostest 

DMSFET710I PHASE 'DOSTEST' ENTRY POINT AT LOCATION 020000. 

R; 

29 start 

DMSLIO740I EXECUTION BEGINS 

R; 

listfile punch output a (label 
FILENAME FILETYPE FM FORMAT 
PUNCH OUTPUT A1 F 

R; 

#cp query reader all 
NO RDR FILES 



TYPE 
DATA 



DIST 
BIN211 



LRECL 


RECS ELOCKS 


DATE 


TIME 


LABEL 


80 


97 10 


9/29/75 


14:50:55 


BBB191 



25 To execute this program in CMS/DOS, punch a file that has fixed-length 80-character 

records into your virtual card punch. If you do not have any files that have 

fixed-length, 80-character records, you can create a file named TEST DATA with the 

CMS editor, or by copying your ASSEMBLE source file with the CCPYFILE command, as 
follows: 

copyfile dostest assemble a test data a 



Use the CP SPOOL command to spool the pu 
the PUNCH command to punch the file. The 
is in your card reader. Use the CP QUERY 
only file in your reader. 

26 Use the ASSGN command to assign SYSIPT 
A-disk. 

27 When you assign a logical unit to a disk 
identify the disk file to CMS. For this 
file named PUNCH OUTPUT. The STATE comma 
exist. If it does exist, rename it, or el 
DLBL command. 

28 Use the GLOBAL command to identify the 
executable phases, then issue the FETCH 
FETCH command loads the executable phase 
executed without the START option, a messa 
location of the program loaded. 

29 The START command begins program executio 
your program completed successfully. You c 
using the LISTFILE command to list the fi 
command, you can see that the file is no 1 



nch to your own virtual machine, then use 
FUN FILE message indicates that the file 
command to check that it is the first, or 

to your card reader and SYSPCH to your 

mode, you must issue the DLBL command to 
program execution, you are creating a CMS 
nd ensures that the file does not already 
se use another filename or filetype on the 

DOSLIB, DOSTEST, you want to search for 

command specifying the phase name. The 

into storage. When the FETCH command is 

ge is displayed indicating the entry point 

n. The CMS ready message indicates that 

an check the input and output activity by 

le PUNCH OUTPUT. If you use the CP QUERY 

onger in your virtual card reader. 
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30 assgn sysipt a 

R; 

dlbl infile a cms punch output (sysipt 

R; 

assgn syspch punch 

R; 

31 fetch dostest (start 
DMSLIO740I EXECUTION BEGINS... 

32 PON FILE 5829 TO BILBO COPY 01 NOHOLD 
R; 

read punch2 output 

R; 

listfile punch2 output a (label 

FILENAME FILETYPE FM FORMAT LRECL RECS ELOCKS DATE TIME LABEL 

PUNCH2 OUTPUT Al F 80 97 10 9/29/75 1U:50:59 BBB191 

R; 



30 If you want to execute this program again, you can assign SYSIPT and SYSPCH to 
different devices; in this example, the input disk file PUNCH OUTPUT is written to 
the virtual punch. You do not need to reissue the GLOBAL DOSLIB command; it remains 
in effect until you reissue it or IPL CMS again. 

31 This time, the program execution starts immediately, because the START option is 
specified on the FETCH command line. 

32 Again, the PUN FILE message indicates that a file has been received in your virtual 
card reader. You can use the CMS command READCARD to read it onto disk and assign it 
a filename and filetype, in this example, PUNCH2 OUTPUT. 
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This sample terminal session shows you how to use access method services under CMS. You 
should have an understanding of VSAM and access method services before you use this 
terminal session. 

The terminal session uses a number of CMS files, which you may create during the 
course of the terminal session; or, you may prefer to create all of the files that you 
need beforehand. Within the sample terminal session, the file that you should create is 
displayed prior to the commands that use it. 

This terminal session is for both CMS OS VSiM programmers and CMS/DOS VSAM 
programmers; all the ASSGN commands and SYSxxx operands that apply when the CMS/DCS 
environment is active are shaded. If you have issued the command SET DOS ON, you must 
enter the shaded entries; if not, you must omit the shaded entries. 

Notes : 

1. This terminal session assumes that you have, to begin with, a read/write CMS A-disk. 
This is the only disk required. Additional disks used in this exercise are temporary 
disks, formatted with the IBCDASDI disk initialization program under CMS. If you 
have OS or DOS disks available, you should use them, and remember to supply the 
proper volume and virtual device address information, where appropriate. The number 
of cylinders available to users for temporary disk space varies among installations; 
if you cannot acquire ample disk space, see your system support personnel for 
assistance. 

2. Output listings created by AMSERV take up disk space, so if your A-disk does not 
have a lot of space on it, you may want to erase the LISTING files created after 
each AMSERV step. 

3. If any of the AMSERV commands that you execute during this sample terminal session 
issue a nonzero return code; for example: 

R (00012); 

You should edit the LISTING file to examine the access method services error 
messages. The publication DOS^VS Mess ag es contains the return codes and reason codes 
issued by access method services. You should determine the cause of the error, 
examine the DLBL commands and AMSERV files you used, correct any errors, and retry 
the command. 

1 #cp define t3330 200 10 

DASD 200 DEFINED 010 CYL 

#cp define t3330 300 10 

DASD 300 DEFINED 010 CYL 

#cp define t3330 400 10 

DASD 400 DEFINED 010 CYL 



These commands define temporary 3330 mindisks at virtual addresses 200, 300, and 
400. 
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File: PUNCH IBCDASDI 

222222 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=200,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=222222 

VTOCD STRTADR=10,EXTENT=5 

END 
333333 JOB 

MSG TODEV=1052,TOADDR=009 

DADEP TODEV=3330,TOADDR=300,VOLID=SCRATCH,CYLNC=10 

VLD NEH?OLID=333333 

VTOCD STRTADR=10,EXTENT=5 

END 
444444 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=400,VOLID=SCRATCH,CyLNO=10 

VLD NEHVOLID=444444 

VTOCD STRTADR=10,EXTENT=5 

END 



File: IBCDASDI EXEC 



6C0NTR0L OFF 

CP CLOSE C 

CP PURGE RDR ALL 

ACC 190 Z/Z IPL * 

CP SPOOL D CONT * 

PUNCH IPL IBCDASDI Z ( NOH 

PUNCH PUNCH IBCDASDI * ( NOH 

CP SPOOL PUNCH NOCONT 

CP CLOSE PUNCH 

CP IPL OOC 



ibcdasdi 

NO FILES PURGED 

DMSACC723I Z (190) R/0 

DMSACC723I 190 ALSO = S-DISK 

PUN FILE 1492 TO BILBO COPY 01 NOHOLD 

IBC105A DEFINE INPUT DEVICE. DASDI 7.77 

input=2540,00c 



2 This file contains control statements for the IBCDASDI progran, which formats and 
initializes disks for OS and DOS. These disks are labelled 222222, 333333, and 
444444. Any messages produced by the IBCDASDI program are sent to your terminal. 

3 This file contains the commands necessary to use the IBCDASDI program under CMS. You 
must punch a copy of the IBCDASDI program, followed by the file containing your 
control statements, to your virtual card reader, and then load the IBCDASDI program. 
This is all done in the file IBCDASDI EXEC. 

4 Execute the IBCDASDI EXEC. The last command in the EXEC is the IPL command, which 
passes control to the IBCDASDI program. The message IBC105A prompts you to enter 
the address of the control statements. 

5 Since the control statements are in your card punch, you indicate the device type 
(2540) and the address (OOC) on the INPUT= statement. 



< 



376 IBM VM/370 CMS User's Guide 



10 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8 

DASDI 7.77 
222222 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=200,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=222222 

VTOCD STRTADR=10,EXTENT=5 

END 
IBC163A END OF JOB. 

DASDI 7.77 
333333 JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=300,VOLID=SCRATCH,CYLNO=10 

VLD NEWVOLID=333333 

VTOCD STRTADR=10,EXTENT=5 

END 
IBC163A END OF JOB. 

DASDI 7.77 
4444Ua JOB 

MSG TODEV=1052,TOADDR=009 

DADEF TODEV=3330,TOADDR=t»00,VOLID=SCRATCH,CYLNO = 10 

VLD NEWV0LID=U4UaUU 

VTOCD STRTADR=10,EXTENT=5 

END 
IBC163A END OF JOB. 

DMKDSP450W CP ENTERED; DISABLED WAIT PSW »0C060000 OOOOEEEE* 
ipl cms 
CMS... VERSION 3.0 02/28/76 

R; 

cp link dosres 350 350 rr read 
DASD 350 LINKED R/O; R/W BY GANDALF 
access 350 z 



DMSACC723I Z 


(350) R/O 


- DO 


set dos on z 


( vsain 




access 


200 b 






DMSACC723I B 


(200) R/W 


- OS 


« 1 

access 


300 c 






DMSACC723I C 


(300) R/W 


- OS 


access 


400 d 






DMSACC723I D 

R; 

query search 


(400) R/W 


- OS 






BBB191 


191 


A R/W 




222222 


200 


B R/W - 


OS 


333333 


300 


C R/W - 


OS 


444444 


400 


D R/W - 


OS 


CMS190 


190 


S R/O 




DOSRES 


350 


Z H/0 - 


BOS 



R; 



6 These messages are issued by the IBCDASDI program, which displays the statements 
executed and indicates the end of each job. 

7 When the last IBCDASDI job is complete, your virtual machine is in the CP 
environment and you must reload the CMS system before you can continue. 

I 8 If you are a CMS/DOS user, you must reaccess the DCS/VSE system residence volume and 
issue the SET DOS ON command line, specifying the VSAM option. If you have not 
previously linked to the system residence, you must use the CP LINK command before 
you issue the ACCESS command. 

9 Access the three newly formatted disks as your B-, C-, and D-disks. 

10 You can issue the QUERY SEARCH command to verify the status of all disks you 
currently have accessed. 
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11 File: MASTCAT AMSERV 

DEFINE MASTERCATALOG - 
( NAME (MASTCAT) - 
VOLUME (222222) - 
CYL (4) - 

OPDATEPW (GAZELLE) - 
FILE (IJSYSCT) ) 

12 ^g^$m;lMt®cmt h 

dlbi ijsysct b dsn mastcat (sjscat perm extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 171 
13 

R; 
14 amserv mastcat 

R; 



15 File: CLUSTER AMSERV 

DEFINE CLUSTER ( NAME (BOOK. LIST ) - 
VOLUMES (222222) - 
TRACKS (20) - 
FILE (BOOK) - 
KEYS (14,0) - 
RECORDSIZE (120,132) ) - 
DATA (NAME (BOOK- LIST-DATA) ) - 
INDEX (NAME (BOOK. LIST. INDEX ) ) 

16 amserv cluster 

a22lA ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV FILE MASTCAT 
gazelle 

R; 

17 File: REPRO AMSERV 

REPRO INFILE (BFILE - 

ENV ( RECORDFORMAT(F) - 
BLOCKSIZE(120) - 
PDEV (3330) ) ) - 
OUTFILE (BOOK) 



11 The file MASTCAT AMSERV defines the VSAM master catalog that you are going to use. 

12 Identify the master catalog volume, and use the EXTENT option on the DLBL command so 
that you can enter the extents. For this extent, specify 171 tracks (9 cylinders) 
for the master catalog. Since 4 cylinders are specified in the AMSERV file, the 
remaining 5 cylinders will be used for suballocation by VSAM. 

13 You must enter a null line to indicate that you have finished entering extent 
information. 

14 Issue the AMSERV command, specifying the MASTCAT file. The ready message indicates 
that the master catalog is created. 

15 Define a suballocated cluster. This cluster is for a key-seguenced data set, named 
BOOK. LIST. 

16 No DLBL command is necessary when you define a suballocated cluster. Note that 
since the password was not provided in the AMSERV file, access method services 
prompts you to enter the password of the catalog, which is defined as GAZELLE. 

17 Use the access method services REPRO command to copy a CMS data file into the 
cluster that you just defined. 

378 IBM VM/370 CMS User's Guide 



> 



18 assgn sysOOl a 
R; 

copy file test data a (recfm f Irecl 120 
R; 

sort test data a book file a 
DMSSRT604R ENTER SORT FIELDS: 
1 1U 

R; 

dlbl bfile a cms book file fisysOOl 

Rf, . . ..,..^^-^ ..^^ 

19 %ssqn"sys06f "IT 

1; 

dlbl book b dsn book list (vsam sys002 

R; 

amserv repro 

R; 

20 File: SPACE AMSER? 

DEFINE SPACE - 

( FILE (SPACE) - 
TRACKS (57) - 
VOLOME (333333) ) 

R: 

assgn sysOOS c 

R; 

21 dlbl space c (extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 57 

R; 

22 amserv space 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV FILE MASTCAT 
gazelle 

R; 






18 You must identify the dnames for the input and output files for the REPRO function. 
BFILE is a CMS file, which must be a fixed-length, 120-character file, and it must 
be sorted alphamerically in columns 1 through 14. The COPYFILE command can copy any 
existing file that you have to the proper record format; the SORT command sorts the 
records on the proper fields. 

19 The output file is the VSAM cluster, so you must use the VSAM option on this DLBL 
command. 

20 Create an AMSERV file to define additional space for the master catalog on the 
volume labelled 333333. 

21 Again, use the EXTENT option on the DLBL command so that you can enter extent 
information, and a null line to indicate that you have finished entering extents. 

22 Issue the AMSERV command. Again, you are prompted to enter the password of the 
master catalog. 
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23 File: UNIQUE AHSERV 

DEFINE CLUSTER - 

( NAME (UNIQUE. FILE) - 

UNIQUE ) - 
DATA - 
( CYL (3) - 

FILE (KDATA) - 

RECORDSIZE (100 132) 

KEYS (12,0) - 

VOLUMES (333333 ) ) - 
INDEX - 
( CYL (1) - 

FILE (KINDBX) - 

VOLUMES (333333) ) 



2H aibl kdata c (extent 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
76 57 

R; 

dlbl kindex c (extent Sf«OiO|t 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
133 19 

R; 

amserv unique 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV FILE MASTCAT 

gazelle 

R; 

25 File: USERCAT AMSERV 

DEFINE USERCATALOG - 
( CYL (4) - 

FILE (IJSYSUC) - 

NAME (PRIVATE. CATALOG) - 

VOLUME {^nnn^n) - 

UPDATEPR (UNICORN) - 

ATTEMPTS (2) ) - 
DATA (CYL (3) ) - 
INDEX ( CYL (1) ) - 
CATALOG (MASTCAT/GAZELLE ) 

26 -assgi' iff «a0ft - 4i 
tl' ' 

dlbl ijsysuc d dsn private catalog (extent sysOOU pern 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 152 

R; 

amserv usercat 

* 

R; 



23 This AMSERV file defines a unique cluster, with data and index conponents. 

24 You must enter DLBL commands and extent information for both the data and index 
components of the unique cluster. 

25 Next, define a private (user) catalog for the volume 444444. This catalog is named 
PRIVATE. CATALOG and has a password of UNICORN. 

26 When you define a user catalog that you are going to use as the job catalog for a 
terminal session, you should use the ddname IJSYSUC. 
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27 TAPE 181 ATTACHED 

28 File: EXPORT AMSERV 

EXPORT BOOK. LIST - 
INFILE (BOOK) - 
OOTEILE (TEMP ENV (PDEV (2U00) 



) ) 



29 



30 



31 



dlbl 














IJSYSCT 


DISK 


FILE 




IJSYSCT 


B1 


MASTCAT 


BFILE 


DISK 


BOOK 




FILE 


A1 




BOOK 


DISK 


FILE 




BOOK 


B1 


BOOK. LIST 


SPACE 


DISK 


FILE 




SPACE 


CI 




KDATA 


DISK 


FILE 




KDATA 


CI 




KINDEX 


DISK 


FILE 




KINDEX 


CI 




IJSYSOC 

13 • 


DISK 


FILE 




IJSYSDC 


D1 


PRIVATE. C 


R; 

aibl book b dsn 

R; 

amserv texport 


book list 


(cat ijsysct 


sy^mz 


(tapout 


181 








DMSAMS361R ENTER TAPE OUTPUT DDNAMES: 




temp 

R; 















32 File: IMPORT AMSERV 

IMPORT - 

CATALOG (PRIVATE. CATALOG/UNICORN) 
INFILE (TEMP ENV (PDEV (2400))) - 
OOTFILE (B00K2) 



► 



33 tape rew 

R; 

dlbl book2 d dsn book list (vsam n 

R; 

amserv timport (tapin 181 

DMSAMS361R ENTER TAPE INPUT DDNAMES 

temp 

R; 



) 



27 You may want to try an EXPORT/IMPORT function, if you can obtain a scratch tape from 
the operator. When the tape is attached to your virtual machine, you receive this 
message. 

28 The file that is being exported is the cluster BOOK. LIST created above. If you do 
not have access to a tape, you can export the file to your CMS A-disk. Remember to 
change the PDEV parameter to reflect the appropriate device type. 

29 Before issuing the AMSERV command to perform the export function, you may want to 
check the DLBL definitions in effect. Issue the DLBL command with no operands to 
obtain a list of current DLBL definitions. 

30 You must reissue the DLBL for BOOK. LIST, because there is a job catalog in effect, 
and the file is cataloged in the master catalog. Use the CAT option to override the 
job catalog. 

31 There is no default tape value when you are using tapes with the AMSERV command. You 
must specify the TAPIN or TAPOUT option and indicate the virtual address of the 
tape- You are prompted to enter the ddname, which for this file is TEMP. 

32 The last AMSERV file imports the cluster BOOK. LIST to the user catalog, 
PRIVATE. CATALOG. 

33 You should rewind the tape before reading it as input. 
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examples 280 
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example 105 
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examples 106 
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example 104 
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examples 104 
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279 
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stacking EXEC files with 294 
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when to use 286 
8TYPEFLAG special variable, testing whether 

EXEC is displaying data 288 
81 through 830, special variables 101 



Index 



383 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8 



! (exclamation point) , controlling whether 
it is displayed 28 



$, used as first character of filename for 

edit macros 311 
$COL edit macro 324 
$CONT EXEC 316 
$DUP edit macro, example 73 
$LISTIO EXEC file 158 
SMACROS edit macro 320 
$MARK edit macro 321 

used to enter continuation character 80 
$MOVE edit macro, how to use 73 
SPOINT edit macro 323 



# logical line end symbol 7 

restriction on stacking in EXEC 

procedure 291 
using to enter null line in input mode 

62 
using when setting program function keys 

340 
#CP function 7, 19 

using in edit or input mode 84 
using on display terminals 339 



a logical character delete symbol 6 

using when setting program function keys 
340 



* (asterisk) 

in EDIT subcommands 65 

in fileids on command lines 44 

in fileids on command lines (5748-XX8) 

44, 1 
in filemode field 53 

used to write comments in EXEC procedure 
305 
♦COPY statement 
examples 138 

in CMS/DOS 166 



= (equal sign) 

entered in fileids on command lines 
entered in filemode field 53 

= subcommand (see REUSE subcommand) 



45 



" logical escape symbol 8 

used when setting program function keys 
340 



/* 

CMS batch iacility control card, used to 

signal end of job 229 
end-of-file indicator 
in AMSERV file 182 
in batch job 237 
// record, used as delimiter in MACLIBs 

140,169 
/ (diagonal) , as delimiter on EDIT 

subcommands 64 
/JOB control card, description 228 
/SET control card, description 229 



% (percent symbol) , setting EXEC arguments 
to blanks 273 



subcommand 
usage 88 

usage, on display terminal 346 
usage as argument for EXEC procedure 
305 
?EDIT message 65 



A 

abnormal termination (abend) , effect on 

DLBL definitions 160 
ACCESS command 

accessing CMS disks 14 

response when you access VSAM disks 185 
used with OS disks 129 
access method services 

control statements, executing 182 
DOS/VS, using in CMS/EOS 181 
DOS/VSE, using in CMS/DOS (5748-XX8) 

181 
executing in CMS, examples 205 
functions 

DEFINE CLUSTER 206 
DEFINE MASTERCATALCG 191,199 
DEFINE USERCATALOG 193,200 
DELETE 207 
EXPORT 208 
IMPORT 208 
REPRO 208 
OS/VS, restriction on using in CHS 181 
return codes 183 
sample terminal session 375 
using in CMS 181 
using tape input/output 204 
in CMS/DOS 196 
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access methods 

DOS, supported in CMS 154 
OS, supported in CMS 130 
accessing 

directories of DOS/VS libraries 163 
directories of DOS/VSE libraries 

( 57 U 8- XX 8) 163 
disks 14 

as read-only extensions 51 
in CMS batch virtual machine 231 
DOS disks 154 

DOS/VS system residence volume 151 
DOS/VSE system residence volume 

(52483XX8) 151 
file directories for CMS disks 57 
files of a particular mode number 55 
multiple access systems with DIAL 

command 26 
OS disks 129 
ACTION 

DOS/VS linkage editor control statement 

173 
DOS/VSE linkage editor control statement 
(5I48:iXX8) 173 
ADD operand 

of MACLIB command 
usage 138 

usage in CMS/DOS 167 
adding 

members to macro library 
example 138 
example in CMS/DOS 167 
address 
stops 

setting 217 

to enter CP environment 23 
virtual 

calculating for instructions in 

program 212 
definition 12 

for unit record devices 113 
A-disk 51 
ADSTOP command, how to set address stops 

217 
ALIAS, OS linkage editor control statement, 

supported by TXTLIB command 146 
ALL 

operand 

of 6BEGSTACK control statement, when 

to use 290 
of &BEGTYPE control statement, when 

to use 287 
of &CONTROL control statement, using 
to debug EXECs 308 
allocating 

space for VSAM files 186,188,202 

in CMS/DOS 194 
VSAM extents on OS disks and minidisks 
198 



ALTER subcommand 

global changes 71 
how to use 70 
altering 

characteristics of spool files 115 
characters in CMS file, with ALTER 

subcommand 70 
multiple occurrences of character in 
file 71 
AMSERV 

command 

executing in EXEC procedure 209 
how to use 182 
files 

examples 182,378 
filetype 182 

usage in CMS 47 
functions under CMS (5748-XX8) 205 
using to read tapes (5748-XX8) 204 
annotated, edit macro 318 
annotating, EXEC procedure 305 
APL, using on display terminal 350 
appending, data to existing files, during 

program execution 134 
arguments 

in EXEC procedure 95,101,272 
checking 274 

passing to nested EXECs 283 
testing with S$ and 8* 274 
on RON command, passing parameter list 

241 
on START command, parameter list 241 
ASB3705 filetype, usage in CMS 47 
ASSEMBLE 
command 

assembling OS programs 143 
in CMS/DOS 171 
filetype 

usage in CMS 47 
used as input to assembler 143 
assembling 

OS programs in CMS 143 
programs 

sample terminal session 366 
using CMS batch facility 235 
programs in CMS/DOS 171 

sample terminal session 371 
source files, from OS disks 143 
VSAM programs in CMS 181 
ASSGN command 

entering before program execution 177 
using to assign logical units 156 
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51 



177 



102 



63 



receiving 
134 

134 



assigning 

filemode letters to disks 
logical units in CMS/DOS 
before program execution 
for VSAM catalogs 193 
to disk devices 158 
to virtual devices 158 
values to variable symbols, in EXEC 
procedure 102 
assignment statement, examples 
attention interruption 
causing 21 

effect of mode setting 30 
automatic 
IPL 6 

save function of CMS editor 
AUTOREAD operand of CMS SET command, 

display terminals 341 
auxiliary control files 259 

preferred 260 
auxiliary processing routine, 
control during I/O operation 
AUXPROC option, of FILEDEF command 
AOXxxxx filetype 

auxiliary control files 259 
usage in CMS 47 



B 
backspace 

characters 

changing in file being edited 78 
deleted in user input area 350 
effect of image setting 78 
entering on display terminal 349 
batch 

facility (see CMS batch facility) 
jobs for CMS batch facility 227 

non-CMS users 236 
processing, in CMS 227 
batch jobs 

purging 233 
reordering 233 
restarting 233 
BDAM, access method, CMS support 130 
BEGIN command, to return to virtual machine 

environment 18 
beginning 

tracing 217 

virtual machine execution 18 



blanks 

as delimiters, on EDIT subcommands 64 
in character strings changed with CHANGE 

subcommand 69 
used on OVERLAY subcommand 70 
blip, characters, setting 28 
BLOCK option, of FILEDEF command 133 
BLP (see bypass label processing) 

(5 74 8- XX 8) 
books 

from DCS/VS source statement libraries, 

copying 161 
from DOS/VSE source statement libraries, 
copying (574 8-XX8) 161 
BOTTOM subcommand, moving current line 

pointer to end of file 66 
BPAM access method, CMS support 130 
branching in EXEC procedure 

SGOTO control statement 277 
SSKIP control statement 279 
based on GIF control statement 276 
BREAK subcommand, setting program 

breakpoints 213 
breakpoints, setting 213 
BSAM access method, CMS support 130 
buffers, used by FSCB 245 
BUFSP option 

of DLBL command 198 
in CMS/DOS 190 
bypass label processing (5748-XX8) 122 



calculating storage available in your 

virtual machine 177 
canceling 

changes made during edit session 63 
DLBL definitions 160 
FILEDEF definitions 134 
verification of changes made by editor 
69 
card punch 

used to send jobs to CMS batch facility 

228 
using in EXEC procedure 296 
card reader 

restriction on use in job for CMS batch 

facility 232 
spooling punch or printer files to 115 
cards 

used as input to CMS batch facility 
228,237 

/* as end-of-file indicator 229 
CASE subcommand, usage 76 
CAT option of DLBL command 198 
identifying catalogs 201 
in CMS/DOS 190,193 
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cataloged procedures, OS, equivalent in CMS 

128 
causing breaks in text (57a8-XX8) 324.11 
CAH (channel address word) , displaying, 

with DISPLAY conmand 220 
CHANGE 

coamand, changing hold status on spool 

files 116 
subcofflffland 

global changes 71 
how to use 69 
using in edit macros 316 
using on display terminal 346 
changing 

characteristics of spool files 115 
characteristics of unit record devices 

113 
file identifier, on SAVE subcommand 85 
filemode numbers 55 

filemode of file, FNODE subcommand 85 
lines in file being edited 69 

that contain backspace characters 78 
multiple occurrences of character string 
in file 71 
changing output representation of a 

character (5748- XX8) 324.13 
channel address word (see CAW (channel 

address word) ) 
channel status word (see CSW (channel 

status word) ) 
character, strings, changing 
characters 
altering 

with ALTER subcommand 
with CHANGE subcommand 
deleting from line 6 
special 

defining translate table for entering 

30 
displaying on display terminal 350 
entering on display terminal 349 
translated to uppercase, in edit macros 

311 
valid in CMS file identifiers 43 
valid in CMS file identifiers (5748-XX8) 
44 
CLASS, operand of SPOOL command 113 
classes 

CP command privilege 333 
of CP spool files 113 
clearing 

console stack 

at top or end of file 313 
for edit macro execution 313 
in EXEC procedure 293 
issuing message after 313 



69 



70 
69 



DLBL definitions 160 

FILEDEF definitions 134 

job catalogs 201 

job catalogs in CMS/DOS 193 
closing 

CMS files, after reading or writing 248 

virtual card punch, after using 8PUNCH 
control statement 296 

virtual unit record devices 250 
clusters, VSAH, defining and deleting 206 
CMS 

operand of DLBL command 160 

saved system name 223 
CMS (Conversational Monitor System) 

basic description 3 

commands (see CMS commands) 

DOS/VS simulation 151 

DOS/VSE simulation (5748-XX8) 151 

file system 43 

file system commands, samples 354 

files ( see files, CMS) 

loading into your virtual machine 6 

OS simulation 127 
CMS batch facility 

control cards 227 
/* 229 
/JOE 228 
/SET 229 

controlling spool files 231 

description 227 

housekeeping done after executing job 
230 

how jobs are processed 230 

jobs for non-CMS users 236 

using EXEC procedure to submit jobs 234 
CMS commands 

executing 

from programs 241 
in edit macros 312 
in EXEC procedure 299 

for tape handling 119 

general information 4 

nucleus-resident 58 

stacking in EXEC procedure 291 

summary 328 

that execute in transient area 58 

used in CMS/DOS (see CMS/DOS commands) 

used with OS data sets 129 

using EXEC procedure to modify 302 

valid in edit macros 312 
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CMS editor 

environment 19 

format of 3270 display screen 345 

how to use 61 

invoking 61 

in EXEC procedure 291 
line mode on display terminal 348 
sample terminal session 354 
using on display terminal 344 
CMS environment 18 
CMS EXEC file 98 
format 98 
modifying 100 
sorting 99 
CMS files (see files) 
CMS macro instructions 
examples 249 
usage 243 
CMS subset 

environment 19,84 
using 90 

using to test EXEC procedure 308 
CMSAMS, saved system name 225 
CMS/DOS 

commands 

ASSGN 156 

ASSGN (5748;XX8) 156.1 
DOSLIB 175 
DOSLKED 172 
DSERV 163 
entering 21 
ESERV 163 
FETCH 175 
LISTIO 158 
PSERV 162 
RSERV 162 

sample terminal session 369 
SSERV 161 
summary 154 
environment 21 

entering 151 
program development using 151 
relationship to CMS and to DOS/VS 151 
relationship to CMS and to DOS/VSE 

(5248zXX8) 151 
restrictions on executing OS programs 
152 
CMSDOS, saved system name 225 
CMSLIB, ddname used to identify OS macro 

libraries 141 
CMSLIB MACLIB 140,169,243 
CMSSEG, saved system name 225 
CMSDTI file,, CMS commands that create 50 
CMSVSAM, saved system name 225 
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CNTRL filetype 
control files 
usage in CMS 
command 

defaults 25 
environments 
how to enter 
language 3 
CMS 4 
CP 3 
lines, how scanned in CMS 240 
comments 

in EXEC procedure 305 
in HELP text files (5748-XX8) 324.7 
communicating 

with CMS and CP during editing session 

84 
with VM/37 3 
COMP 

operand of MACLIB command 
usage 139 

usage in CMS/DOS 168 
COMPARE command, comparing contents of CMS 

files 39 
comparing, variable symbols in EXEC 

procedure 105,276 
compilers, supported in CMS 4 
components, of VM/370 3 
compressing 

DOSLIB files 175 
MACLIBs 139 

in CMS/DOS 168 
COHCAT option, of FILEDEF command, example 

141 
conditional execution, &LOOP control 

statement 280 
conditionally displaying text (5748-XX8) 

324,8 
console 
log 

creating disk file from 342 
printing 342 

produced by CMS batch facility 233 
output, spooling for display terminal 

342 
stack 

cleared in case of error during edit 

macro execution 314 
clearing 293 
clearing for edit macro execution 

313 
using in EXEC procedure 289 
using to write edit macros 311 
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CONT 

operand of SPOOL command 114 

using to spool virtual punch in EXEC 
procedure 297 
continuation character, how to enter in 

column 72 79 
continuous spooling 114 
control cards, for CMS batch facility (see 

CMS batch facility control cards) 
controlling 

CMS loader 147 

execution of EXEC procedure, summary of 

control statements 103 
intensity of the redisplay of user input 
(5748^XX8) 28 
converting 

decimal values to hexadecimal, in EXEC 

procedure 270 
fixed-length files to variable-length 

format 75 
hexadecimal values to decimal, in EXEC 
procedure 270 
CONHAIT function 
example 295 

using to clear console stack 293 
COPY 

files 

adding to MACLIB 138 
adding to MACLIB, in CMS/DOS 166 
f iletype 

usage in CMS 47 
usage in CMS/DOS 49 
function, on display terminals 342 
operand of SPOOL command 114 
COPYFILE command 

changing filemode numbers 55 
changing record format of file 75 
copying files from one virtual disk to 

another 32 
creating small files from large one 89 
copying 

books from DOS/VS source statement 

libraries 161 
books from DOS/YSE source statement 

libraries {5748::XX8) 161 
contents of display screen 342 
DOS files into CMS files 155 
files 

from one device to another 118 
from tape to disk 122 
lines in CMS file 73 
macros from DOS/VS libraries to add to 

CMS MACLIB 165 
macros from DOS/VSE libraries to add to 

CMS MACLIB (5748-XX8) 165 
members of MACLIBs 139,168 
modules from DOS/VS relocatable 
libraries 162 



modules from DOS/VSE relocatable 

libraries (5748-XX8) 162 
OS data sets into~CMS files 135 
parts of CMS file, with GETEILE 

subcommand 73 
spool files 114 
VSAM data sets 208 
into CMS files 208 
copying modules from DOS library or SYSIN 

tapes (5748::XX8) 156 
core image libraries 

CMS (see DOSLIB files) 
DOS/VS, using in CMS/EOS 164 
DOS/VSE, using in CMS/DOS (5748-XX8) 
164 
correcting, lines as you enter them 6 
counters, using in EXEC procedure 280 
CP (control program) 
basic description 3 
commands, general information 3 
privilege classes 333 
spooling facilities 113 
CP commands 19 

executing from programs 242 

summary 334 

used for debugging 220 

compared with DEBUG subcommands 222 
using in EXEC procedure 267 
using in job for CMS batch facility 232 
CP environment, entering 17 
CP HEAD status, on display screen 340 
creating 

CMS EXEC file 98 
CMS files 31 

from DOS disks and tapes 156 
from DOS libraries 155 
from OS data sets 
in EXEC procedure 
CMS macro libraries 
example 137 
example in CMS/DOS 
from DOS macro libraries 165 
DOSLIB files 174 

file system control block (FSCB) 244 
files with CMS editor 61 
HELP text files (5748-XX8) 324.4 
modules from DOS library or SYSIN tapes 

(5748-XX8) 156 
one spool file from many files being 

printed or punched 114 
program modules 149 

programs, sample terminal session 365 
reserved filetypes 303 
user-written commands 149 
user-written edit macros 311 
CSW (channel status word) , displaying, with 

DISPLAY command 220 
current line pointer . 

displaying when verification is off 86 

how to use 65 

position on display terminal screen 344 

positioning 68 

subcommands for display terminals 347 
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cylinders 

extents 

entering in CMS/DOS 192 
specifying for OS disks 198 

on 23ia/2319 disk 199 

on 3330 disk 199 

on 3340 Model 35 disk 199 

on 3340 Model 70 disk 199 



data control block (DCB) , relationship to 

FILEDEF command 131 
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DEBUG 

command 20 
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monitoring program execution 213 
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debugging 220 
summary 215 
debug environment 20 
debugging 
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command 25 
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command 
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logical line editing symbols 8 
program input and output files in CMS 
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temporary disks 12 
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virtual storage 223 
VSAM files 
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of MACLIB command 138 
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DISCONN, command 26 
disconnecting, your terminal from your 

virtual machine 26 
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DISK 

command 
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using synonyms 29 

while command or program is executing 
22 
continuation character in column 72 79 
CP commands 

from CMS command environment 18 

from edit environment 84 
CP environment 

after program check 220 

during program execution 23 

from CMS environment 17 

from edit mode 84 
debug environment 

after program abend 212 

via breakpoint 20,213 

via DEBUG command 20 

via EXTERNAL command 20 

via external interruption 217 
DEBUG subcommands 20 

DLBL definitions, in EXEC procedure 179 
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EXEC 
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command 
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HELPCMS filetype, usage in CMS (5748:2XX8) 

47 
HELPCP filetype, usage in CMS (5748-XX8) 
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information 

about CMS files 39,99 

about disks 40 

about DOS files 154 

about MACLIB members 139,168 
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about OS and DOS disks 187 
about OS and DOS files 40 
about your terminal 38 
about your virtual machine HO 
logical unit assignments in CMS/DOS 158 
listing files 

created by AMSERV command 
changing filename 184 
printing 184 
created by assembler, output filemode 

143 
created by assembler and language 

processors 48 
created by ESERV command 163 
LISTING filetype 

created by AMSERV command 183 
usage in CMS 47 
usage in CMS/DOS 49 
LISTIO command, listing device assignments 

158 
literal values, using in EXEC 269 
LKEDIT filetype, usage in CMS 47 
LOAD, command, loading and executing TEXT 

files 144 
load ioap 

produced by LOAD and INCLUDE commands 

147 
using when debugging 211 
LOAD MAP file, created by CMS loader 147 
loader 
CMS 

description 146 
entry point determination 148 
control statements, summary 147 
tables 

effect of LOAD and INCLUDE commands 

147 
usage 223 
loader terminate (LDT) loader control 

statement, usage 145 
loading 

alternate saved segment on IPL command 

225 
CMS into your virtual machine 6 

specifying virtual device address 
224 
core image phases into storage for 

execution 175 
programs into storage, specifying 

storage locations 243 
TEXT files into storage 144 
TXTLIB members 

dynamically 148 
into storage 145 



LOADLIB filetype, usage in CMS 47 
LOADMOD command, to debug MODULE file 221 
LOCATE subcommand 
how to use 67 
using in edit macros 316 
locating 

lines in file being edited 67 
using line-number editing 82 
location, starting, for loading link-edited 

phases 176 
locking, terminal keyboard to wait for 

communication 30 
logging off VM/370 26 
logging on to VM/370 5,25 
logical 

character delete symbol 6 
escape symbol 8 
line delete symbol 7 
line editing symbols 6 
defining 8 
overriding 28 
overriding (5748-XX8) 28.1 
used with editor 62 
line end symbol (see also # logical 

line end symbol) 
line end symbol 7 
operators, used for comparisons in EXEC 

procedure 105 
record length of CMS file, overriding 

editor defaults 74 
units 

assigning in CMS/DCS 156 
assigning in CMS/DOS {5748-XX8) 
156.1 
LOGOFF command 26 
LOGON command 25 

contacting VM/370 5 
LONG, subcommand, when to use 86 
loop 

during program execution, debugging 216 
in EXEC procedure 105 

based on number of arguments passed 

273 
using SLOOP control statement 279 
using counters 280 
lowercase letters 

suppressing translation to uppercase 76 
translated to uppercase by editor 62 
LRECL option 

of COPYFILE command, truncating records 

in file 74 
of EDIT command, when to use 74 
of FILEDEF command, when to specify 133 
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M 
MAGLIB 

command 

usage 137 

usage in CMS/DOS 164 
files 

adding MACRO files created by ESERV 

program 163 
moving to other files 140,169 
querying 137 
querying, in CMS/DOS 164 
filetype, usage in CMS 47 
MACRO 
files 

adding to MACLIB 138 
adding to MACLIB in CMS/DOS 167 
created by ESERV command 163 
filetype 

usage in CMS 47 
usage in CMS/DOS 49 
macro libraries 
CMS 136 

adding to 138 

creating 137 

deleting members of 138 

displaying information about members 

in 139 
distributed with CMS system 140,169 
replacing members of 138 
using in CMS/DOS 164 
DOS/VS assembler language, restriction 

on using in CMS/DOS 164 
DOS/VSE assembler language, restriction 

on using in CMS/DOS (5748-XX8) 164 
OS, identifying for use in CMS 140 
macros 

DOS/VS assembler language 
creating CMS MACLIB 372 
supported in CMS 170 
DOS/VSE assembler language 

creating CMS MACLIB (5748zXX8) 372 
supported in CMS (5748-XX8) 170 
OS, supported in CMS 142 
MAINHIGH 177 
MAP 

filetype 

created by DOSLKED command 175 
created by DSERV command 163 
created by MACLIB command 139,168 
usage in CMS 47 
usage in CMS/DOS 49 
written to A-disk 54 
operand 

of MACLIB command 139,168 
option of DOS/VS ACTION control 

statement, effect in CMS/DOS 175 
option of DOS/VSE ACTION control 
statement, effect in CMS/DOS (5748-XX8) 
175 



maps 

created by DOS/VS linkage editor 175 
created by DOS/VSE linkage editor 

(5748-XX8) 175 
of CMS virtual storage 224 
margins 

setting left margin for input with 

editor 77 
setting right margin for input with 
editor 79 
master catalogs 
VSAM 

defining 199 
defining in CMS/DOS 191 
sharing 185 
master file directory 56 

maximum, number of records in CMS file 43 
MEMBER option 

CMS commands that have MEMBER option 

168 
of FILEDEF command 134 

to copy member of OS partitioned data 
set 135 
MEMO filetype 50 
MESSAGE command, using before logging on 

25 
messages 

controlling whether you receive them 26 

from CMS batch facility 230 

from CP during edit session, effect on 

display screen 346 
from editor, on display terminal 344 
to other virtual machine users 25 
minidisks (see also disks) 
definition 11 
transporting to OS system after using 

with CMS VSAM 187 
using with VSAM data sets 187 
EXPORT/IMPORT restriction 208 
mode 

edit and input 62 
setting for your terminal 22,30 
switching 17 
summary 24 
modifying 

CMS EXECS 100 

CMS files, examples of commands 33 
FSCB 245 

groups of CMS files 53 
registers during program execution 212 
MODULE 
files 

creating 149 
debugging 221 
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executing from programs 242 
generating, to execute in transient 

area 243 
modifying 221 
filetype, usage in CMS 48 
modules 

DOS/VS relocatable, copying into CMS 

files 162 
DOS/VSE relocatable, copying into CMS 
files (5748-XX8) 162 
MORE... status, on display screen 341 
MOVEFILE command 

copying OS data sets 134 

copying tape files 122 

copying tape files (5748-XX8) 122 

extracting member of MACLIB 140,169 

moving labelled tapes (5748::XX8) 122 

reading files from virtual card reader 

118 
used with OS data sets 129 
moving 

CMS files, examples of commands 33 
current line pointer 65 
lines in file being edited 73 
MULT option of DLBL command 198 

in CMS/DOS 190 
multiple 

extents for VSAM files 
specifying 203 
specifying in CMS/DOS 195 
output devices, restriction in CMS/DOS 

159 
updates 257 

variable symbols in token, examples 269 
multivolume VSAM extents 
specifying 204 
specifying in CMS/DOS 195 



N 

NAME, OS linkage editor 
supported by TXTLIB co 
naming 

CMS files 43 
CMS files (5248-XX8) 
user commands 58 
naming conventions for 

<5748-XX8) 324,3 
nesting 

&IF statements in EX 
EXEC procedure 282 
return code passe 
NL (see no label proce 
nnnnn subcommand, examp 
no label processing (57 
NODISP option of EDIT c 

EXEC procedure 349 
nonrelocatable modules, 
nonshared copy 
of CMS 224 
of saved system, obt 
debugging 224 
nonstandard label proce 
122 



control statement, 
mmand 146 
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HELP text files 



EC procedure 277 
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ssing) (5748-XX8) 

les 82 

ii8zXX8) 122 

ommand, using in 
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aining during 
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NOPROF option 

suppressing 
NOT ACCEPTED 
NSL (see non 

(5 74 8- XX 8) 
nucleus-resid 
null 
line 

after I 
at top 
enterin 
how to 
in EXEC 
stackin 
testing 
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mode 
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, of ACCESS command, 
execution of PROFILE EXEC 98 
status, on display screen 341 
standard label processing) 

ent CMS commands 58 



PL 6 

of file 66 

g to determine environment 17 

enter 3 

procedure 267 
g in EXEC procedure 210,292 

for in EXEC procedure 285 
me program execution after 
ion interruption 22 
rn to edit mode from input 
62 
in EXEC procedure 102 



object files 

created by assembler a 

processors 48 
loading into storage 
offsetting text (5748-XX8 
opening, CMS files 248 
options, for FILEDEF comm 
OREER command, selecting 

processing 116 
origin, for debug environ 
ORIGIN, subcommand, how t 
OS 

access methods support 
data sets 

copying into CMS fi 
restrictions on rea 
using in CMS 129 
disks 

compatibility with 

using in CMS 129 

linkage editor control 

by TXTLIB command 14 

macros supported in CM 

partitioned data sets 

data sets) 

program development 

sample terminal ses 

summary of commands 

simulated data sets 1 

simulation in CMS 127 

utility programs, crea 

from tapes created by 



nd language 

144 

) 324.10 

and 133 
files for 

ment, setting 214 
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DOS disks 186 
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S 142 

(see partitioned 



sion 365 

35 
30 

ting CMS files 
122 



Index 



401 



Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8 



OSMACRO MACLIB 140,169 
0SMACR01 MACLIB 140,169 
output 

files, produced by ASSEMBLE command 172 

from CMS batch facility 233 

from virtual console, spooling 342 
OOTPOT, operand, of CMS SET command, 
defining output translate table 30 
output stack, clearing 293 
OVERLAY subcommand 

how to use 70 

overlay more than one line 71 

using in edit macros 316 
overlaying 

character strings 70 

with $MARK edit macro 321 

virtual storage, during program 
execution 243 
overriding, logical record length of file 
being edited 74 



parameter lists 

detecting absence of 241 
passing with START command 144,241 
setting up to execute CMS command 241 
used by CMS routines 240 
using FSCB 244 
parent disk, of read-only extension 52 
parentheses, scanned by EXEC interpreter 

267 
partition size, specifying for program 

execution, in CMS/DOS 178 
partitioned data sets 

copying into CMS files 135 
specifying member names with FILEDEF 
command 134 
passing 

arguments 

to EXEC procedure 272 
to nested EXEC procedure 283 
control in EXEC procedure 277,279 
password suppression on command line 

13,25,57 
passwords 

entering on LOGON command line 25 
for VSAM catalogs 202 

in CMS/DOS 194 
for your virtual machine 5 
supplying on LINK command line 13 



PA1 key, to enter CP environment 344 

PDS option, of MOVEFILE command, to copy OS 

partitioned data sets 135 
periods, used to concatenate EXEC variable 

symbols 103 
PERM option, of FILEDEF command, when to 

specify 134 
PF keys (see program function keys) 
phases, CMS/DOS core image, writing into 

BOSLIBs 174 
positioning 

current line pointer 65,68 

using $POINT edit macro 323 
tapes, examples 120 
preferred auxiliary files 260 
preferred level updating 260 
preparing, jobs for CMS batch facility 231 
PRESERVE subcommand 

saving EDIT subcommand settings 86 
using in edit macros 315 
preserving, editor settings 86 
PRINT 

access method services function, output 

183 
command, printing CMS files 34 
printer files 

produced by job running in batch virtual 

machine 231 
querying status of 115 
printing 

access method services listings 184 
CMS files 34 
multiple copies 114 

trace information on virtual printer 
218 
PRINTL macro, usage 250 
privilege classes, for CE commands 
PROC filetype 162 

usage in CMS/DOS 49 
procedures 

DOS/VS, copying into CMS files 
DOS/VSE, copying into CMS files 
(5748-XX8) 162 
PROFILE EXEC 
sample 97 

for CMS/DOS VSAM user 191 
for OS VSAM user 199 
program 

abend, message 211 

check, using CP to debug 220 

debugging 211 

dumps, obtaining 221 
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execution 

entry point determination 148 
interrupting 21 

resuming with BEGIN command 221 
tracing 216 
input and output files, identifying 131 
interruptions 

address stops 23 
breakpoints 23 
libraries 145 
linkage, in CMS 239 
listings, using when debugging 211 
loops, debugging 216 
program development 
DOS programs 151 

sample terminal session 
summary of commands 36 
OS programs 127 

sample terminal session 
summary of commands 35 
using CMS 125 
program function keys 
setting 339 

COPY function 342 
for EDIT subcommands 348 
in EXEC procedure 340 
logical tab stops 349 
using 339 
program status word (see PSW (program 

status word) ) 
programmer logical units, assigning in 

CMS/DOS 157 
prompting 

for line numbers while line-number 

editing 82 
messages in EXEC procedure 284 
protecting, files from being accessed 54 
PSERV command, examples 162 
PSW, operand of DISPLAY command 216 
PSW (program status word) 
displaying 

in debug environment 212 
while program loops 216 
with DISPLAY command 220 
modifying wait bit 220 
PUNCH 

command 

example 117 

punching jobs to batch virtual 

machine 228 
using with SPDNCH control statement 
297 
ESERV control statement, executing in 
CMS/DOS 163 



punch files, produced by job running in 
batch virtual machine 231 

PONCHC macro, usage 250 

punching 

CMS files 34 

files to your virtual card punch 117 

jobs to batch virtual machine 228 

in EXEC procedure 234 
lines in EXEC procedure 107 
lines to virtual card punch 118 
members of MACLIBs 139,169 

POBGE, command, purging spool files 116 

purging batch jobs 233 



Q 

QSAM access method, CMS support 130 

QUERY 

command (CHS) , used with OS data sets 

129 
command (CP) , displaying status of spool 
files 115 
QUIT subcommand, terminating edit session 
63 



RDTERM macro, examples 250 
read, to virtual console^ definition 21 
READ control card, punching 117 
READCABE command 
examples 117 

restriction in CMS batch facility 232 
used to assign filemode numbers 56 
using with 8PUNCH control statement 296 
READER operand 

of ASSGN command, restriction in job for 

CMS batch facility 232 
of EILEDEF command, restriction in job 
for CMS batch facility 232 
reading 

arguments from terminal during EXEC 

processing 276 
cards from your virtual card reader 116 
CMS commands 

from console stack 291 
from terminal during EXEC processing 
285 
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CMS files 

from console stack 294 
from EXEC procedure 294 
with FSREAD macro 246 
DOS files in CMS 154 
files from tapes 119 
from terminal 

in EXEC procedure 106 
RDTERM macro 250 
lines from console stack, in EXEC 

procedure 289 
real card decks into your virtual 

machine 117 
specific records in CMS file 246 
variable symbols from terminal during 
EXEC processing 285 
read-only, extensions, using 51 
read/write 

pointer, positioning 248 
status of disks 
displaying 14 

in VM/370 directory entry 11 
ready message 8 

controlling how it is displayed 27 
CPU times displayed 239 
displaying return code from EXEC 

procedure 284 
not displayed after #CP function used in 
CMS environment 19 
RECFM, option, of FILEDEF command, when to 

specify 133 
record format 

describing for file being edited 73 
of CMS file, changing 75 
specifying for DOS files 155 
specifying for program input and output 
files 133 
record length 

creating long records with editor 74 
of CMS file 

changing 74 

default values set by editor 74 
relationship to file size 75 
records, in CMS file, maximum number 43 
recursion level of EXEC, testing with 

&GLOBAL special variable 283 
red type, displaying error messages in 28 
re-executing, EDIT subcommands 87 
register 15 

checking contents after program 
execution 150 
in CMS/DOS 179 
contents after CMS command execution 

240 
testing contents in EXEC procedure 301 



registers (see general registers) 
relative record number, specified in FSCB 

245 
RELEASE command 14 

updating master file directory 57 
used with OS disks 129 
releasing 

disks 14,57 

read-only extensions 52 
relocatable 

modules, link-editing in CMS/DOS 174 
object files, loading into storage for 
execution 146 
Remote Spooling Communications Subsystem 
(see RSCS (Remote Spooling Communications 
Subsystem) ) 
remote terminals, using CMS editor 348 
RENAME command, renaming CMS files 33 
renaming, CMS files 33 
RENUM subcommand, usage 82 
renumbering, records in file, while 

line-number editing 82 
reordering batch jobs 233 
REP 

operand 

of MACLIB command 138 
of MACLIB command in CMS/DOS 167 
REPEAT subcommand, used with OVERLAY 

subcommand 71 
REPLACE 

option of COPYFILE command, used to 

change filemode letters 55 
subcommand 

how to use 72 
using in edit macros 315 
replacing 

lines in file being edited 72 

using line-number editing 82 
members in macro library, example in 
CMS/DOS 167 
REPRO, access method services function 208 
resolving, unresolved references 147 
responding 

to CMS commands in EXEC procedure 107 
to prompting messages from AMSERV, in 
EXEC procedure 209 
responses 

from CMS commands 9 

suppressing display in EXEC procedure 
287 
from CP commands 9 
from VM/370 8 

to CMS commands, stacking in EXEC 
procedure 289 
restarting batch jobs 233 
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RESTORE 

subcommand 
usage 87 

using in edit macros 315 
restoring 

editor settings 87 
screen display during edit session, 
using TYPE subcommand 346 
restrictions 

on commands used in CMS batch facility 

232 
on ddnames in OS VSAM programs 197 
on executing DL/I programs in CMS/DOS 

152 
on executing DOS programs in CMS/DOS 

175 
on executing OS programs in CMS 14U 
on executing OS programs in CMS/DOS 152 
on number of files per disk (57U8-XX8) 

43 
on number of lines that can be stacked 

in edit macro 314 
on programs executing in transient area 

243 
on reading DOS files in CMS 155 
on reading OS data sets in CMS 131 
on using DOS/VS macro libraries in 

CMS/DOS 164 
on using DOS/VSE macro libraries in 

CMS/DOS (57 4 8- XX 8) 164 
on using minidisks with VSAM data sets 
187 
resume 

program execution 

after attention interruption 22 
after program check 212 
terminal displays 22 

in EXEC procedure 288 
RETURN 

CMS subset command, to leave CMS subset 

20 
DEBUG subcommand, before starting 
program execution 213 
return codes 

displayed in ready message 240 
from access method services 183 
from CMS commands 

displaying during EXEC processing 

299 
specifying error address following 
SVC 202 242 
from EXEC procedure 284 
in CMS ready message 9 
passed by register 15 240 
1 299 
-2 314 
-3 299 



REUSE subcommand 

after LOCATE or FIND subcommand 67 

usage 87 
RSCS (Remote Spooling Communications 
Subsystem) 3 

general information 123 
RSERV command, examples 162 
RT Immedia,te command 22 

executing in EXEC procedure 288 
RUB, command, specifying arguments 241 
RUNNING status, on display screen 341 



SAM files (see sequentia 

(SAM) files) 
sample, terminal sessions 
SAVE subcommand 

changing file identifi 
writing file onto disk 
scanning 

CMS command lines 240 
lines in EXEC procedur 
tokens in EXEC procedu 
screen 

example of 3270 screen 
format used by CMS edi 
status 

CP READ 340 
CP READ (5748-XX8) 
HOLDING 341 
MORE... 341 
NOT ACCEPTED 341 
RUNNING 341 
VM READ 341 
SCRIPT 

command, restriction 

CMS/DOS 152 
files 50 

using backspaces 
filetype, usage in CMS 
SCROLL subcommand, how to 
search order 

for CMS commands 

considerations when 

procedure 302 
summary 59 
for CMS disks 51 
displaying 14 
for executable phases 
used by DOSLKED comman 
searching 

disks for CMS files ( 

determination) 
for label in EXEC proc 
for line in file being 



1 access method 

353 

er 85 
62 



e 267,309 
re 100 

display 343 
tor 345 



340.1 



on executing in 



78 



48 
use 347 



naming EXEC 



in CMS/DOS 176 
d 172 

see disk 

edure 278 
edited 67 
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27 



only particular columns of file being 

edited 69 
read-only extensions 52 
segment 

alternate, loading on IPL command 225 
shared system loaded into 221 
sending messages, to other virtual machine 

users 25 
sequence numbers 

specifying identifier 80 
updating 254 
sequential access method (SAM) files, 

reading in CMS/DOS 154 
serial numbers 

changing verification setting to display 

81 
in file being edited 80 
SERIAL subcommand, examples 80 
serializing 

records in file 80 

while line- number editing 
SET command (CHS) 

controlling message displays 
operands invalid in job for CMS batch 

facility 232 
setting implied CP and EXEC functions 
29 
SET command (CP) , controlling message 

displays 26 
SETSSI, OS linkage editor control 
statement, supported by TXTLIB command 
146 
setting 

entry point for program execution 148 
limits on system resources during batch 

jobs 229 
program function keys 339 
in edit macros 340 
sharing 

CMS system 223 

data and master catalog, in CMS VSAH 

185 
virtual disks 13 
SHORT subcommand, when to use 86 
simulated data sets 

filemode number of 4 55 
format 130 
size 

of CMS file 
maximum 43 

relationship to record length 75 
of virtual storage in your virtual 
machine 223 



skipping, lines in EXEC procedure 279 
SLEEP command 

locking terminal keyboard 30 
using on display terminals 341 
SMSG command (CP) 27 
sorting 

CMS EXEC 99 

directories of DOS/VS libraries 163 
directories of DOS/VSE libraries 
(5748-XX8) 163 
spacing between lines of text (5248-XX8) 

324.11 
special characters 

CMS editor handling 76 
on 3270 terminals 349 
3270 Text feature 352 
special messages, controlling whether you 

receive them 26 
special variables, EXEC (see EXEC special 

variables) 
specifying 

device type for FILEDEF command 132 
filemode numbers, on ELEL and FILEDEF 

command 56 
which records to read or write 246 
splitting, CMS files into smaller files 89 
SPOOL command 

changing characteristics of unit record 

devices 113 
spooling console output 342 
spool files 113 

controlling in job for CMS batch 

facility 231 
determining status of 41,115 
produced by CMS batch facility, 
controlling 233 
spooling 

basic description 113 
console output 342 
multiple copies 114 
SSERV command, examples 161 
STUCK, subcommand, using in edit macros 

317 
stacking 

CMS commands, in EXEC procedure 291 
command lines, after attention 

interruption 22 
commands lines, with # (logical line end 

symbol) 7 
EDIT subcommands 291 
in edit macros 311 
with REUSE subcommand 88 
EXEC files in console stack 294 
Immediate commands in EXEC procedure 
287 
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last-in first-out in EXEC procedure 290 
lines in console stack, in EXEC 

procedure 289 
lines in EXEC procedure 107 

limitations 289,314 
null lines 

after attention interruption 22 
in EXEC procedure 210,292 
responses in EXEC procedure 289 
AMSERV command 209 
DLBL command 179 
FILEDEF command 150 
to CMS commands 107 
START 

command 

after LOAD command 144 
used with FETCH command 175 
option 

of FETCH command 176 
of LOAD command 144 
starting, program execution in CMS 144 
STATE command, used with OS data sets 129 
STEPCAT, CMS equivalent 128 
storage available in your virtual machine, 

calculated by CMS 177 
STORE 

CP command, using to change program 

status word (PSW) 216 
subcommand, changing storage locations 
214 
suballocated VSAM cluster, defining 206 
submitting 

jobs to CMS batch facility 227 
non-CMS users 236 
substituting, variable symbols in EXEC 

procedure 268 
summary 

of CMS commands 328 
of CMS/DOS commands 154 
of CP command privilege classes 333 
of CP commands 334 
of DEBUG subcommands 215 
of EDIT subcommands 91 
of EXEC built-in functions 103 
of EXEC control statements 109 
of EXEC special variables 112 
of Immediate commands 327 
suppressing 

long form of editor ?EDIT message 86 
verification of changes made by editor 
86 



suppression of passwords on the command 

line 13,25,57 
SVC 

instructions 

tracing with CP TRACE command 218 
tracing with SVCTRACE command 219 
SVC 202, used to call CMS command 241 
SVCTRACE command, usage 219 
symbolic addresses for tapes 118 
symbols 
debug 

defining 214 

using with DEBUG subcommands 214 
logical line editing 6 
used for comparisons in EXEC procedure 

105 
variable^ in EXEC procedure (see 
variable symbols) 
SYNONYM 

command, invoking synonym tables 29 
filetype, usage in CMS 48 
synonyms, for CMS and user-written 

commands, defining 29 
SYSCAT, assigning in CMS/DCS 190 
SYSCLB 

assigning in CMS/DOS 157 
unassigning 176 
SYSIN 

assigning in CMS/DOS 157 
input for ESERV command 163 
SYSIPT, assigning in CMS/DCS 157 
SYSLIB, ddname used to identify OS macro 

libraries 141 
SYSLOG, assigning in CMS/DCS 157 
SYSLST 

assigning in CMS/DOS 157 
output from ESERV program 163 
SYSPCH 

assigning in CMS/DOS 157 
output from ESERV program 163 
SYSRDR, assigning in CMS/DOS 157 
SYSRLB, assigning in CMS/DCS 157 
SYSSLB, assigning in CMS/DOS 157 
system disk, files available 54 
system logical units 157 
SYSUT1 filetype 50 
SYSDT2 filetype 50 
SYSUT3 filetype 50 
SYSUT4 filetype 50 
SYSxxx 

option of DLBL command 159 
programmer logical units 
assigning 156 
assigning (5748-XX8) 156.1 
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SYS004 
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filetype 
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T 
tab 

characters 

deleted in user input area 350 
entering in file being edited 76 
using in edit macros 316 
using on display terminals 3U9 
settings, used by editor 77 
TABSET subcommand, using in edit macros 

316 
TAPE command, examples 120 
TAPEMAC command, use in tape label 

processing (57 482XX8) ''22 
tapes 

considerations for CMS/DOS users 156 

controlling 118 

density of, when to specify 123 

for AMSERV, example 208 

labels 121 

end-of-tape processing (57a8-XX8) 

122 
end-of-volume processing (57483XX8) 

122 
error processing (52M=XX8) 122 
processing in CMS 156 
processing in CMS (5748-XX8) 121,133 
processing in CMS/DOS T57a8-XX8) 122 
processing in OS simulation 

(5748- XX8) 122 
reading 204 
reading in CMS/DOS 197 
used for AMSERV input and output 204 
in CMS/DOS 196 
TAPESL macro, use in tape label processing 

(5748;XX8) 122 
TAPn, symbolic addresses for tapes 118 
TAPPDS command 

copying files from tapes 122 
copying files from tapes {5748-XX8) 122 
use in tape label processing (5748-XX8) 
122 
temporary disks, using for VSAM data sets 

188 
TERMINAL, command, setting logical line 

editing symbols 8 
terminals 

characteristics, setting 28 

commands to control communications 25 

communication in EXEC procedure 284 

disconnecting 26 

display (see display terminals) 

input buffer (see console stack) 

macros for communication 248 

mode setting 22,30 

display terminals 341 
sample sessions 353 
terms, OS, equivalents in CMS 128 



testing 

arguments passed to EXEC procedure 274 
EXEC procedure, using CMS subset 308 
for null line entered in EXEC procedure 

285 
return codes from CMS commands 283 

in EXEC procedure 284 
variables symbols, using SIF control 
statement 276 
TEXT 

assembler output ddname, overriding 

default definition 143 
files 

created by assembler and language 

processors 48 
link-editing in CMS/ECS 172 
loading into storage 145 
filetype 

usage in CMS 48 
usage in CMS/DOS 49 
text feature, for 3270 terminals 352 
time information, displaying during EXEC 

processing 300 
TO, operand of SPOOL command 115 
TOP, token stacked when edit macro executed 

at top of file 313 
TOP: message 66 
tokens 100 

with multiple variable symbols 269 
TOP, subcommand, moving current line 

pointer to top of file 66 
top of file 

executing edit macros 313 
indication in file being edited 66 
TRACE, command, usage 217 
tracing 

output, printing 218 
program execution 216 
controlling trace 218 
tracks 

entering extent information in terms of 

198 
number per cylinder on disk devices 199 
TRANSFER command, moving reader files 116 
transferring 

control in EXEC procedure 

&ERHOR control statement 301 
using 8G0T0 control statement 277 
transient area 

CMS commands that execute in 58 
creating modules to execute in 243 
location in virtual storage 223 
restrictions on modules executing in 
243 
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translate tables 

defining input and output characters for 

30 
using on display terminals 349 
translating, virtual storage to EBCDIC 219 
translating output characters (5748-XX8) 

324.13 
transporting, VSAM data sets 208 
TRONC 

option of COPYFILE command, used to 

convert record formats 75 
subcommand, setting right margin for 
input with editor 79 
truncating 

data while changing lines with editor 

79 
input data while using editor 78 
trailing blanks from fixed-length 

records 75 
words in EXEC procedure 267 
truncation, settings used by editor 79 
TSOMAC MACLIB 140,169 
TXTLIB 

command 

OS linkage editor control statements 

supported 145 
usage 145 
files 

assigning entry point names 145 
manipulating 145 
filetype, usage in CMS 48 
members, assigning names for 146 
TYPE 

command, displaying CMS files 34 
subcommand 

effect on current line pointer 65 
using to restore screen display 346 
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unassigning logical unit assignments in 

CMS/DOS 158 
underscore 

characters in file being edited 78 
using on OVERLAY subcommand 70 
unique clusters, defining 206 
unit record, devices 113 
unresolved references, how CMS loader 

resolves 147 
UPDATE 

control statement usage 253 
filetype 

creating update files 252 
usage in CMS 48 



updating 

CMS file directories 57 

source files 251 
examples 255,256 
UPELOG filetype, usage in CMS 48 
UPDTxxxx filetype, usage in CMS 48 
UPSI 

byte, setting in CMS/DOS 178 

operand, of CMS SET command, example 
178 
user catalog 

VSAM 200 

in CMS/DOS 193 
user file directory 56 
user program area 223 

executing programs and CMS commands 243 
userid 

for your virtual machine 5 

of CMS batch virtual machine 228 

specifying for output spool files 114 
user-written 

commands, creating 149 

edit macros 320 



variable symbols 

compound 269 

examples of substitution 268 

how scanned 268 

in EXEC procedure 101 
comparing 105 
using as counters 280 

reading values from terminal 285 

stacking in edit macros 312 
variable-length EXEC files, considerations 

for writing edit macros 315 
VARS operand of 8READ control statement 

285 
verification setting 

changing in edit macros 315 

changing on display terminal 346 

columns used by editor 69 
VERIFY subcommand 

canceling editor displays 86 

how to use 69 

using in edit macros 315 
verifying, execution of edit macros 315 
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virtual 

addresses 

for disks 12 
for tapes 118 

for unit record devices 113 
storage (see virtual storage) 
virtual disks (see also disks) 

definition 11 
Virtual Machine Facility/370 (VM/370) 
basic description 3 
command summaries 328 
components 3 
environments 17 
virtual machines 
definition 3 
size 223 
virtual storage 

addresses, calculating 212 

CMS utilization 224 

displaying 219 

examining in debug environment 212 

how CMS uses 223 

increasing size 89 

overlaying during program execution 2U3 

specifying locations for program 

execution 243 
used by editor, what to do when it is 
full 88 
VM READ status, on display screen 341 
VMFASM EXEC procedure 262 
VMFDOS command (5248-XX8) 156 
VM/370 (see Virtual Machine Facility/370 

(VM/370)) 
vm/370 online 5 
VSAM 

access method, CMS support 130 
catalogs 

deleting 207 
passwords 202 
passwords in CMS/DOS 194 
using in CMS/DOS 190 
clusters 

defining 206 
deleting 207 
unique 206 
data sets, manipulating with AMSERV 

command 181 
files 

allocating space for 186 
identifying multivolume 204 
identifying multivolume in CMS/DOS 

196 
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t and output files 

efining 197 

efining in CMS/DOS 

er catalog 

efining 199 

efining in CMS/DOS 

dentifying 199 

dentifying before executing programs 

182 

dentifying in CMS/DOS 

haring 185 

ivolume extents 

pecifying 204 

pecifying in CMS/DOS 

on 

f DLBL command 197 

f ELBL command, in CMS/DOS 190 

rams, compiling and executing in CMS 
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catalogs 
efining 200 
efining in CMS/DOS 192 
g in CMS 181 
rogram, invoking on display terminal 



wait bit, in program new PSW, modifying 

220 
WAITT macro, usage 250 
warning messages, controlling whether you 

receive them 27 
writing 

CMS files 

in EXEC procedure 296 
with FSWRITE macro 246 
CMS files onto disk 

disk determination 54 
how editor selects disk 63 
edit macros 311 

error messages in EXEC procedure 306 
labels on CMS disks 12 
lines to terminal 250 
specific records in CMS file 246 
tape marks, examples 120 
WRTERM macro, examples 250 
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DEBUG subcoMoiand, exanple 211 
EDIT subccBiand, usage 87 



ZONE subcommand 

setting truncation columns for CHANGE 

subcommand 79 
specifying columns for editor to search 
69 



T subcommand, usage 87 



ZAP filetype, usage in CMS 48 
zone setting 

columns used by editor 69 

increasing 79 



19E virtual disk address, accessed as 

Y-disk 51 

19C virtual disk address 

accessed as S-disk 51 

using to IPL CMS 6 

191 virtual disk address, accessed as 
A-disk 51 

192 virtual disk address, accessed as 
D-disk 51 



3270 terminals (see display terminals) 
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